ghostrules 0.2.0__tar.gz → 0.3.0__tar.gz

{ghostrules-0.2.0 → ghostrules-0.3.0}/.ghostrules.lock

@@ -3,22 +3,22 @@
     "claude-code": [
       {
         "conditions": [],
-        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 030e09c253572539 ba2cd86d7e76eff5 3b81b7bc3295aca9 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 8e5a481cbb86370a f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "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": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
-        "seen_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
         "via": []
       }
     ],
     "copilot-cli": [
       {
         "conditions": [],
-        "lines": "2a3d3f1fb26381e9 e3b0c44298fc1c14 ddabff43c0a4efe5 6aa552cc1598dcb7 be186e6b970ab643 fb78540ec32b52f9 e3b0c44298fc1c14 d393a517d5cbec9f e3b0c44298fc1c14 85b7ae55df076ab0 2f6995b0ecd75c8d e3b0c44298fc1c14 5f2235a1b010f82c 030e09c253572539 ba2cd86d7e76eff5 3b81b7bc3295aca9 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 8e5a481cbb86370a f75f6ee8f0d942eb 1f59b655e6071114 da29957f3e8be475",
+        "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": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
-        "seen_sha256": "dc7776630751bba0d3c39e83e96b3b6dae1de7cd5630b49e3b0f7853bbbf1f3f",
+        "raw_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
+        "seen_sha256": "c21de91b03da043818a3d8a83418a2e4ce449e58e1e6a5906e7d7c2212ddfca5",
         "via": []
       }
     ],
@@ -26,6 +26,6 @@
     "generic": []
   },
   "configs": [],
-  "generator": "ghostrules 0.2.0",
+  "generator": "ghostrules 0.3.0",
   "lock_version": 1
 }

{ghostrules-0.2.0 → ghostrules-0.3.0}/.ghostrules.toml

@@ -7,4 +7,6 @@ exclude = [
   ".mypy_cache/**",
   ".ruff_cache/**",
   ".pytest_cache/**",
+  "corpus/.cache/**",  # API responses and clones are other people's text
+  "corpus/results/**",
 ]

ghostrules-0.3.0/.github/workflows/corpus.yml

@@ -0,0 +1,79 @@
+name: Corpus
+
+# Runs ghostrules against the public repositories listed in corpus/repos.toml (the only networked
+# part of the project). Never on pull requests.
+on:
+  schedule:
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: corpus
+  cancel-in-progress: false
+
+jobs:
+  corpus:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ghostrules from this checkout
+        run: pip install -e ".[dev]"
+      - name: Scan the regression tier
+        run: python corpus/run.py --tier regression
+      - name: Gate against labels.toml
+        run: python corpus/check.py
+      - name: Aggregate files (badge and summary, counts only)
+        if: always() && hashFiles('corpus/results/latest-summary.json') != ''
+        run: python corpus/badge.py --out corpus-public
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: corpus-results
+          path: |
+            corpus/results
+            corpus-public
+          retention-days: 30
+          if-no-files-found: ignore
+
+  publish:
+    # Only the default branch publishes; the badge reads corpus/badge.json from gh-pages.
+    needs: corpus
+    if: always() && needs.corpus.result != 'skipped' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: corpus-results
+          path: artifact
+      - name: Publish to gh-pages
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          test -f artifact/corpus-public/badge.json
+          git clone --quiet --depth 1 --branch gh-pages \
+            "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" site \
+            || { mkdir site && git -C site init --quiet -b gh-pages \
+              && git -C site remote add origin \
+              "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"; }
+          mkdir -p site/corpus
+          cp artifact/corpus-public/badge.json artifact/corpus-public/summary.json site/corpus/
+          cd site
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add corpus
+          git diff --cached --quiet || git commit --quiet -m "corpus: weekly summary"
+          git push origin gh-pages

ghostrules-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,48 @@
+name: Playground
+
+# Builds the browser playground (web/ plus the wheel of this checkout) and deploys it to GitHub Pages.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[dev,web-test]"
+      - name: Build the site
+        run: python scripts/build_site.py _site
+      - name: Playwright smoke test on the built site
+        run: |
+          playwright install --with-deps chromium
+          pytest -q tests/web
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

{ghostrules-0.2.0 → ghostrules-0.3.0}/.gitignore

@@ -12,3 +12,9 @@ dist/
 htmlcov/
 *.ghostrules.bak
 ghostrules.sarif
+
+# corpus tooling
+corpus/.cache/
+corpus/results/*
+!corpus/results/latest-summary.json
+_site/

ghostrules-0.3.0/CHANGELOG.md

@@ -0,0 +1,203 @@
+# 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.3.0] - 2026-10-28
+
+Measurement release. ghostrules now runs against real repositories every week, a browser playground
+runs the real scanner without installing anything, and the first full study of popular repositories
+drove a round of precision fixes. On the 300-repository regression tier 0.2.1 reported 323 findings
+(84 critical, 156 high); 0.3.0 reports 212 (0 critical, 53 high), every critical and high finding
+reviewed. On the 1,283-repository study tier the first run reported 1,072 findings (13 critical, 296
+high); after the fixes 945 (12 critical, 252 high), all of medium and above triaged.
+
+### Added
+- **Playground** (`web/`, `.github/workflows/pages.yml`): a static page that runs the real scanner in
+  the browser with Pyodide. Paste a file, drop a folder (agent files and what they import, up to
+  5 MB) or name a public GitHub repo (the only tab that uses the network). Shows what you see versus
+  what the agent reads, the context tree per agent and downloadable JSON, Markdown and SARIF reports.
+  Playwright smoke test; deployed to GitHub Pages on release tags.
+- **Corpus tooling** (`corpus/`, outside the package and the wheel): `discover.py`, `run.py`,
+  `check.py`, `triage.py`, `badge.py`, `filestats.py`, a weekly `corpus.yml` workflow and an endpoint
+  badge in the README. Findings are labelled by fingerprint in `corpus/labels.toml`; labels never
+  name a repository for a reported finding.
+- **Study tooling** (`study/`): per-repository features, aggregate CSVs, SVG charts in light and dark,
+  the triage classes and `study/report.md`, generated from the CSVs.
+- `ghostrules.playground`, `ghostrules.reveal_data` and `ghostrules.reporters.context_data`: the core
+  (scanner, rules, context engine, JSON, SARIF and Markdown reporters) now imports without `typer`
+  and `rich`; the terminal output is unchanged.
+- `action.yml` is named `ghostrules scan` and its description fits the Marketplace limit (125
+  characters).
+
+### Fixed
+- GR003: a lone U+200B between two letters of Khmer, Thai, Lao or Myanmar text is that script's word
+  separator and is ignored.
+- GR005: a hidden comment is `medium` when it carries an instruction cue, `low` when it only mentions
+  agents, `high` unchanged for injection matches.
+- GR010: `override system|safety` needs a following noun, and defensive text that quotes the phrase
+  is `low`.
+- GR011: `without asking the user` is no longer concealment; a prohibition earlier in the clause, a
+  safety claim ("does not silently install"), a description in the third person ("silently runs") and
+  a modal before it are not reported.
+- GR012: naming the `curl | sh` pattern without a target is `low`; a `curl` in prose no longer joins
+  the next code block; `| bash script.sh` is not a data pipe into the shell.
+- GR013: needs a verb, a secret and a URL in the same clause; prohibitions, loopback URLs, `POST`
+  and `.post(`, "send the user to" and "send X only to the fixed origin" are not exfiltration.
+- GR014: the verb must govern the path across no paragraph break, clause connector (`before`,
+  `after`, `when`), passive or noun use; `### Output` is a heading; `.env.default` and copying a
+  dotenv file are not reads.
+- GR015: runs inside URLs, Subresource Integrity digests and low-entropy hex (`AAAA…`) are skipped.
+- GR016: a prohibition ("Avoid `--yolo`"), a table row and a list item that documents a flag are not
+  an instruction.
+- A bare `@/`, `@~/`, `@./` or `@../` is a path prefix, not an import.
+
+### Known limits
+- Splitting an exfiltration instruction across two sentences avoids the GR013 prose match, and a
+  concealment right after an unrelated prohibition in the same clause is not reported.
+
+## [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.2.0 → ghostrules-0.3.0}/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.2.0 → ghostrules-0.3.0}/CONTRIBUTING.md

@@ -17,10 +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),
-`AGENT_MODELS.md` (how each agent loads its instructions, with sources) and `DECISIONS.md`
-(choices made where they were ambiguous). `docs/v0.2/` holds the 0.2 design documents. 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
 

{ghostrules-0.2.0 → ghostrules-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ghostrules
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find the instructions your AI agent sees but you don't.
 Project-URL: Homepage, https://github.com/BardLaudian/ghostrules
 Project-URL: Documentation, https://github.com/BardLaudian/ghostrules#readme
@@ -45,33 +45,40 @@ Requires-Dist: rich>=13
 Requires-Dist: tomli>=2.0; python_version < '3.11'
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
 Requires-Dist: jsonschema>=4; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: pyyaml>=6; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: study
+Requires-Dist: matplotlib>=3.8; extra == 'study'
+Provides-Extra: web-test
+Requires-Dist: playwright>=1.45; extra == 'web-test'
 Description-Content-Type: text/markdown
 
 # ghostrules
 
 *Know exactly what your AI agent reads — and approve every change to it.*
 
-*Find the instructions your AI agent sees but you don't.*
+**[Try it in your browser →](https://bardlaudian.github.io/ghostrules/)** Paste an `AGENTS.md`, drop a folder or name a public repo. It runs the real scanner in the page: your files never leave it.
 
 [![CI](https://github.com/BardLaudian/ghostrules/actions/workflows/ci.yml/badge.svg)](https://github.com/BardLaudian/ghostrules/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/ghostrules.svg)](https://pypi.org/project/ghostrules/)
 [![Python versions](https://img.shields.io/pypi/pyversions/ghostrules.svg)](https://pypi.org/project/ghostrules/)
+[![Corpus](https://img.shields.io/endpoint?url=https%3A%2F%2Fbardlaudian.github.io%2Fghostrules%2Fcorpus%2Fbadge.json)](https://github.com/BardLaudian/ghostrules/blob/main/corpus/README.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/BardLaudian/ghostrules/blob/main/LICENSE)
 
-![ghostrules finds an instruction hidden in an innocent-looking AGENTS.md](https://raw.githubusercontent.com/BardLaudian/ghostrules/main/demo/demo.gif)
+![A CLAUDE.md that looks clean imports a file that imports a file with a hidden instruction; ghostrules finds it and shows the chain](https://raw.githubusercontent.com/BardLaudian/ghostrules/main/demo/imports.gif)
 
-`ghostrules` scans a repository (and, if you ask, your machine) for **hidden instructions and risky
-configuration in the files AI coding agents read and obey**: `AGENTS.md`, `CLAUDE.md`,
-`.cursorrules`, Copilot instructions, skills, MCP configs and more. It models how each agent
-loads those files (imports, rules that apply to some paths, what it strips), so it scans what the
-agent really reads, and it can pin that and show every change to it. It runs as a CLI, a GitHub
-Action (with SARIF for the Security tab) and a pre-commit hook.
+`ghostrules` finds the instructions your AI agent sees but you don't. It scans a repository (and, if
+you ask, your machine) for **hidden instructions and risky configuration in the files AI coding
+agents read and obey**: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Copilot instructions, skills, MCP
+configs and more. It models how each agent loads those files (imports, rules that apply to some
+paths, what it strips), so it scans what the agent really reads, and it can pin that and show every
+change to it. It runs as a CLI, a GitHub Action (with SARIF for the Security tab) and a pre-commit
+hook.
 
 It is a defensive tool. It only **reads** files and reports findings: it never executes anything it
 finds, never makes network requests and never phones home. Secrets it finds are always printed
@@ -114,10 +121,16 @@ influences what the agent does, and a reviewer cannot see everything that is in
 | **Telling the agent to misbehave** (GR010–GR016) | "Ignore previous instructions", hiding actions from the user, `curl … \| sh`, sending `.env` or keys to a URL, reading `~/.ssh`, base64 payloads, `--dangerously-skip-permissions`; in English and Spanish |
 | **Risky configuration** (GR101–GR108) | Hardcoded tokens in MCP configs, unpinned `npx`/`uvx` servers, `http://` remotes, a filesystem server on `/`, shell wrappers, `docker --privileged`, `bypassPermissions`, auto-enabled project MCP servers |
 
+The oldest trick is still the hidden Unicode one: an innocent-looking `AGENTS.md` that carries an
+instruction only the model can read.
+
+![ghostrules finds an instruction hidden in an innocent-looking AGENTS.md](https://raw.githubusercontent.com/BardLaudian/ghostrules/main/demo/demo.gif)
+
 ### How it works
 
-1. It finds the agent files (see [Supported agents and files](#supported-agents-and-files)). Symbolic
-   links are never followed.
+1. It finds the agent files (see [Supported agents and files](#supported-agents-and-files)). A
+   symbolic link is an alias only when it ends at a file inside the repository (`CLAUDE.md ->
+   AGENTS.md`); it is never followed out of it.
 2. It runs the rules on each one. Rules are pure functions over the text: no I/O, no execution.
 3. Hidden text (tag characters, variation selectors, base64) is **decoded and scanned again**, and
    what it contains is reported one severity level higher.
@@ -167,8 +180,8 @@ Findings ───────────────────────
 
 The imported file is scanned like any instruction file, and its findings carry the chain that
 leads to it. Imports are followed the way the agent follows them: relative to the importing file,
-not inside code spans or code blocks, to the documented depth, never through a symbolic link and
-never outside the repository (GR020 reports those). An import of a credentials file such as `.env`
+not inside code spans or code blocks, to the documented depth, never outside the repository
+(GR020 reports those) and never through a symbolic link that leaves it (GR025). An import of a credentials file such as `.env`
 is reported (GR021) and the file is never read.
 
 | `context` option | Default | Meaning |
@@ -347,7 +360,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: BardLaudian/ghostrules@v0.2.0
+      - uses: BardLaudian/ghostrules@v0.3.0
         with:
           fail-on: high          # critical | high | medium | low | info | none
           all-files: "false"     # also check every text file for hidden Unicode
@@ -380,7 +393,7 @@ output `lock-exit-code` is `0` up to date, `1` changed, `2` the check could not
 ```yaml
 repos:
   - repo: https://github.com/BardLaudian/ghostrules
-    rev: v0.2.0
+    rev: v0.3.0
     hooks:
       - id: ghostrules
 ```
@@ -421,7 +434,7 @@ the URLs in any file.
 | <a id="gr022"></a>`GR022` | low | instructions | **Import that silently does not load.** An @path the agent ignores: missing file, too deep, quoted path or a path cut at a space. |
 | <a id="gr023"></a>`GR023` | info | instructions | **Import cycle.** Files that import each other in a loop. Agents stop at the depth limit; it is only noise. |
 | <a id="gr024"></a>`GR024` | info | instructions | **Payload reached only through an import.** Not a detector: findings in a file that only an @import reaches carry the import chain and the tag reached-via-import. Disabling it stops ghostrules from following imports. |
-| <a id="gr025"></a>`GR025` | medium | instructions | **Symlinked instruction source.** An instruction file or rules directory that is a symlink. ghostrules never follows it. |
+| <a id="gr025"></a>`GR025` | high | instructions | **Symlinked instruction source.** An instruction file or rules directory that is a symlink the agent would follow out of the repository, a broken or cyclic one, or a symlink checked out as a text file. A link whose target is a file inside the repository is an alias and is not reported. |
 | <a id="gr101"></a>`GR101` | critical | config | **Hardcoded secret in agent config.** API keys and tokens written into MCP server env/args/headers/URLs or agent settings env. |
 | <a id="gr102"></a>`GR102` | medium | config | **Unpinned package execution.** MCP servers launched with npx/uvx/etc. without an exact version run whatever is latest. |
 | <a id="gr103"></a>`GR103` | high | config | **Insecure remote MCP transport.** Remote MCP servers reached over plain http:// expose traffic and credentials. |
@@ -455,7 +468,11 @@ Matching is case-insensitive on file names. `--home` adds the user-level files m
 On top of these patterns, `ghostrules` scans every file the modelled agents load: files reached
 through `@path` imports and `.claude/rules/**/*.md`, for instance.
 
-Symbolic links are never followed during repository scans. Known agent files are always scanned
+A symbolic link whose final target is a file inside the repository (`CLAUDE.md -> AGENTS.md`, or a
+`.claude/rules/shared -> ../shared-rules` directory) is an **alias**: the agent reads the target
+under the link's name, `context` shows `CLAUDE.md → AGENTS.md (symlink)`, the content is scanned
+once, and findings say they were reached through the link. A link that leaves the repository, is
+broken or loops is never read (GR025). Known agent files are always scanned
 whatever their size, so padding a file cannot hide it; the 2 MB and binary-file limits only
 apply to the extra files `--all-files` adds.
 
@@ -525,7 +542,8 @@ request can update it; what it gives you is that any change to what the agents r
 explicit, reviewable diff. Put `.ghostrules.lock` and the instruction files in `CODEOWNERS`.
 
 **Does it follow imports that leave the repository?** No. `@/etc/hosts` and `@~/notes.md` are
-reported (GR020) and never read, and `ghostrules` never follows a symbolic link (GR025).
+reported (GR020) and never read, and `ghostrules` never follows a symbolic link out of the
+repository (GR025).
 
 **Which files does it look at?** The agent files in the table above. `--all-files` extends the
 hidden-Unicode checks to every text file; `exclude` and `extra_targets` in the configuration adjust
@@ -535,6 +553,21 @@ the list.
 Findings below that level are still reported but do not change the exit code, and `--fail-on none`
 never fails.
 
+## How we test precision
+
+A scanner that cries wolf gets switched off, so precision is measured, not assumed. Every week a
+workflow scans 300 popular public repositories with agent files (`corpus/`, the only part of the
+project that uses the network) and fails if a critical or high finding has not been reviewed. Each
+false positive found that way became a test and a rule change; findings that are correct matches in
+a harmless context (a `curl | sh` installer in a README) are labelled and kept. On the first run of
+the 300 repositories 0.2.1 reported 84 critical and 156 high findings; 0.3.0 reports none critical
+and 53 high, all reviewed.
+
+The same tooling scanned 1,583 repositories for
+[a study of what popular repositories tell their AI agents](https://github.com/BardLaudian/ghostrules/blob/main/study/report.md):
+aggregates only, no repository is named next to a finding, and every number comes from the CSVs in
+`study/data/`.
+
 ## Limits
 
 `ghostrules` is a set of heuristics, not a proof: no findings does not mean a file is safe, and some
@@ -546,8 +579,8 @@ running server.
 The agent models follow each agent's public documentation and say `(unverified)` where it is
 silent. They do not see what lives outside the repository or the machine: Cursor user and team
 rules, managed policy files, Claude Code's `claudeMdExcludes` and `--add-dir`, instructions turned
-off inside Copilot with `/instructions`. A `CLAUDE.md` that is a symbolic link is reported but not
-read. The lock is a visibility control, not a barrier (see above).
+off inside Copilot with `/instructions`. A symbolic link that leaves the repository is reported but
+not read. The lock is a visibility control, not a barrier (see above).
 
 ## Roadmap