ghostrules 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -26,6 +26,6 @@
     "generic": []
   },
   "configs": [],
-  "generator": "ghostrules 0.2.1",
+  "generator": "ghostrules 0.3.0",
   "lock_version": 1
 }

{ghostrules-0.2.1 → 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.1 → 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.2.1 → ghostrules-0.3.0}/CHANGELOG.md

@@ -5,6 +5,59 @@ 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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ghostrules
-Version: 0.2.1
+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,21 +45,29 @@ 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.*
 
+**[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)
 
 ![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)
@@ -352,7 +360,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: BardLaudian/ghostrules@v0.2.1
+      - 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
@@ -385,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.1
+    rev: v0.3.0
     hooks:
       - id: ghostrules
 ```
@@ -545,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

{ghostrules-0.2.1 → ghostrules-0.3.0}/README.md

@@ -2,9 +2,12 @@
 
 *Know exactly what your AI agent reads — and approve every change to it.*
 
+**[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)
 
 ![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)
@@ -297,7 +300,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: BardLaudian/ghostrules@v0.2.1
+      - 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
@@ -330,7 +333,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.1
+    rev: v0.3.0
     hooks:
       - id: ghostrules
 ```
@@ -490,6 +493,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

{ghostrules-0.2.1 → ghostrules-0.3.0}/action.yml

@@ -1,7 +1,5 @@
-name: ghostrules
-description: >-
-  Find hidden instructions and risky configuration in the files AI coding agents read and obey
-  (AGENTS.md, CLAUDE.md, .cursorrules, skills, MCP configs...). Read-only: nothing is executed.
+name: ghostrules scan
+description: Find hidden instructions and risky settings in AGENTS.md, CLAUDE.md, .cursorrules, skills and MCP configs.
 author: Pablo Seoane Temprano
 branding:
   icon: eye-off

{ghostrules-0.2.1 → ghostrules-0.3.0}/docs/DECISIONS.md

@@ -742,3 +742,150 @@ out `low` (example), FIXES.md expects `medium`. Two changes:
   ..."), so the sentence is a description. A code span that is the whole clause, or is followed by a
   verb or "and", stays a directive (`` `cat ~/.ssh/id_rsa` `` is still high).
 Corpus after the change: n8n l.649 is `medium`; the other three remaining findings are unchanged.
+
+## v0.3 Phase 1 — corpus tooling
+
+- **Location and packaging.** `corpus/` is outside `src/`, so the wheel (which packages only
+  `src/ghostrules`) never contains it; the sdist excludes `/corpus` in `pyproject.toml`.
+  `tests/test_corpus_packaging.py` builds both with hatchling and checks the file lists (`hatchling`
+  is in the `dev` extra). The scripts import each other as top-level modules (`import common`), so they
+  run as `python corpus/x.py`; the tests add `corpus/` to `sys.path`.
+- **No shell, one injectable layer.** Every `git`, `gh` and `ghostrules` call goes through a `Runner`
+  (list of arguments, never a shell); tests use `tests/corpus_fakes.FakeRunner`. Repository names are
+  validated before they reach any command (no leading `-` or `.`, so never an option).
+- **Measurement is isolated.** `run.py` always passes `--config <empty file>` and runs from a directory
+  outside the clone, so a scanned repo's `.ghostrules.toml` cannot change the result. The command is
+  `python -I -c "from ghostrules.cli import app; app()"` because the package has no `__main__`.
+- **Stored results.** No `message` or `fix_hint`; `snippet` is re-masked with `mask_secrets` and passed
+  through `safe_text` (repository content may carry terminal escapes); `decoded` only for GR001/GR004;
+  context only as counts and readable paths. `triage.py` re-fetches the file with `gh api` for display
+  only.
+- **Labels and privacy.** `labels.toml` is committed, so `reported` and `tp` labels never name the
+  repository (only `fp` and `wontfix`, which are benign, do). Messages from `check.py` carry the
+  fingerprint, not the repository. An `fp` label must record its old severity and an existing test.
+- **check.py exit codes.** 1 = unlabelled critical/high, `fp` at or above its old severity, `fp`
+  without an existing test. 2 = a scan, context run or timeout failed (or no run exists). A failed
+  clone is reported but is not a gate: repositories get renamed or deleted.
+- **discover.py.** Responses (200/404/409/451) are cached forever in `corpus/.cache/` (`--refresh`
+  ignores it); a rate-limited reply sleeps until `X-RateLimit-Reset`. A truncated tree is `null`
+  ("unknown"). `--propose` picks round-robin across languages, most starred first, as a starting point
+  only: the human edits the list.
+- **Real check (2026-10-28).** `run.py --repos getsentry/sentry-python,anthropics/claude-agent-sdk-python`:
+  both `ok`, 2 findings (low), `check.py` PASS.
+
+## v0.3 Phase 2 — first corpus run (2026-10-28, 300 repos, regression tier)
+- **Selection.** `discover.py`, 10 languages x 250 most-starred candidates (>= 2,000 stars, pushed
+  within 6 months), 1,112 with agent files; the 300 are 30 per language, round-robin, approved by the
+  user. Biased to popular repositories by construction.
+- **First run:** 323 findings, 240 critical/high in 37 repos, three repos produced 158 of them.
+  Nothing from GR001/GR004/GR015/GR101/GR021 at medium or above: no secret or hidden payload found.
+- **GR013 (82 critical).** Causes: `POST` matched as a verb (`curl -X POST`, `requests.post(`); a
+  verb, a word like "token" and a URL anywhere within 80/200 characters of normalised text (it joined
+  list items and code); prohibitions ("Never send credentials ..."); loopback URLs; "send the user
+  to". Fixed with a same-clause requirement, the other exclusions above and the directive /
+  descriptive / example severity. Known evasion: splitting the verb and the URL into two sentences
+  avoids the *prose* match; hidden decoded text is exempt from that filter.
+- **GR010 (67 high).** Defensive guidance quoting "ignore previous instructions". Now classified; and
+  `override system|safety` requires a following noun.
+- **GR012.** `curl ... | sh` named as a pattern (block lists, "must be rejected") is `low`.
+- **Disclosure:** none needed so far.
+- **Approved by the user (2026-10-28), changes to the contract:** (A) GR011 no longer matches
+  `without asking the user` and ignores matches under a prohibition; (B) GR014: `.env.default` is a
+  template, a local `copy` of a dotenv file does not fire, a bold/code-wrapped prohibition counts;
+  (C) a GR016 match in a Markdown table row is at most medium (not applied to GR010, so a table row
+  cannot hide an override). Known evasion: a real concealment preceded by an unrelated "not ..." within
+  the 40 characters before it is not reported.
+- **Approved by the user (2026-10-28), D and E:** (D) GR003 ignores a lone ZWSP between letters of
+  Khmer/Thai/Lao/Myanmar (found in the Khmer translation of an AGENTS.md); (E) GR005 is medium only
+  with `you must|always|never`, low when the comment only names the agent, high unchanged when it
+  matches GR010-GR016. Also fixed (bug, no contract change): GR012 folded a prose "curl" onto the
+  `curl ... | bash` of the next code block (spans that cross a code fence are dropped *before*
+  deduplication; dropping them afterwards would have lost the real command).
+- **More GR012 data pipes (corpus run 5):** `curl … | bash scripts/extract.sh "$tag"` runs a script from
+  a file (an argument with a `/` or a `.sh` suffix) and is not matched, like `python script.py`;
+  `| bash`, `| sh -s -- …` and `| sudo sh` still are. A pattern named inside a Markdown table cell
+  with an escaped pipe (`curl ... \| bash`) is also a mention.
+
+## v0.3 Phase 3 — corpus CI and badge
+
+- **Badge text:** `corpus · 300 repos · 0 critical`, not "0 false positives". What the gate proves is
+  that no critical/high finding is unreviewed, so the badge reports the critical count of the latest
+  run and turns red ("gate failing") when `check.py` would fail.
+- **Published files:** `corpus/badge.py` writes `badge.json` and `summary.json` with counts only
+  (no repository names, paths, snippets or per-repository timings), so the public branch carries
+  nothing that identifies a repository or a finding. The full results stay in the workflow artifact
+  (30 days).
+- **Publishing:** weekly `schedule` and `workflow_dispatch`, never on pull requests. The `publish`
+  job runs only on `refs/heads/main` and writes `corpus/badge.json` and `corpus/summary.json` to
+  `gh-pages` with the job's `GITHUB_TOKEN` (`contents: write` on that job only). The README badge
+  reads `https://bardlaudian.github.io/ghostrules/corpus/badge.json`, which needs GitHub Pages
+  enabled on `gh-pages`.
+
+## v0.3 Phase 4 — web playground
+
+- **Core without typer/rich:** `reveal.py` and `reporters/context.py` mixed data and `rich` drawing.
+  The data moved to `reveal_data.py` and `reporters/context_data.py` (the old modules re-export), so
+  the core imports without `typer`/`rich` (tested in a subprocess with them blocked). The wheel
+  installs in Pyodide 0.27.7 with `micropip.install(..., deps=False)`; no in-memory filesystem
+  adapter was needed (Pyodide's emulated FS is enough).
+- **Bridge:** `ghostrules.playground` takes `{path: text}`, writes it to a temporary directory,
+  scans it and returns plain data (findings, per-agent context tree, revealed lines, JSON/Markdown/
+  SARIF reports). Paths with `..`, absolute paths and NULs are refused; limits are 5 MB and 500 files.
+- **Folder and GitHub loading:** the page lists paths first, asks Python which are agent files
+  (`agent_paths`, the target globs plus `.claude/rules/**/*.md`) and reads only those, then follows
+  `@imports` (relative to the importing file, up to 6 rounds, `imported_paths`). Files over 1 MB are
+  skipped.
+- **Rendering:** all file content is inserted with `textContent`, never as HTML. "What you see"
+  drops invisible characters and HTML comments; "What the agent reads" shows them as tokens.
+- **Deploy:** `pages.yml` (release tags and manual) builds the site with `scripts/build_site.py`,
+  runs the Playwright smoke test (`tests/web`, skipped when playwright is missing, GitHub calls
+  mocked) and deploys with SHA-pinned official actions. The demo's hidden text is generated in JS,
+  so no invisible characters are stored in the repository.
+
+## v0.3 Phase 5 — study tooling
+
+- **Selection (approved):** 3 stars strata (500-1999, 2000-9999, 10000+) x the 10 languages of the
+  regression tier (Rust, JavaScript, C++, Java, Ruby, Go, C#, Python, TypeScript, PHP), the 150
+  most-starred candidates per cell, public, non-fork, non-archived, pushed within 6 months, with at
+  least one agent file; about 500 repos per stratum, round-robin across languages. The regression
+  repos are excluded from `study` and the report uses both tiers together.
+- **`run.py` records more numbers:** per context entry its load kind, import depth, whether it is
+  conditional and which transforms apply; per file (`filestats.py`) kind (agent / imported), size,
+  lines, symlink and its in-repo target, a 16-hex content hash (to find duplicated files) and the
+  number of HTML comments. No text is stored. Symlinks are read with `lstat`/`readlink`, never followed.
+
+- **Study precision fixes (2026-10-28, first study run, 1,283 repos).** Real false positives, fixed
+  with tests in `tests/test_precision_study.py`: GR011 (prohibition anywhere in the clause; bare verb
+  only; modal / "either" before `silently`), GR016 (prohibition in the clause; a list item that opens
+  with the flag documents it, so medium), GR013 ("send X only to the fixed/official/configured …
+  origin" restricts where data goes, so it is descriptive, not critical), GR015 (runs inside URLs, SRI
+  digests, `AAAA…` padding), imports (a bare `@/`, `@~/`, `@./`, `@../` is a prefix, not a file).
+  Known evasions: a real concealment preceded by a prohibition in the same clause is not reported;
+  "send it only to the official https://attacker.example" is medium, not critical.
+- **Left as they are (labelled in triage, not rule bugs):** GR003 on characters that really are in
+  the text (word joiner before `mapbox://`, a ZWSP demonstration in a security skill), GR012 on known
+  installers (`curl … | sh`), GR014 "read the `.env`" instructions in a project's own file, GR107 allow
+  lists, GR105 `bash` wrappers, GR020 imports that really leave the repository.
+
+- **Study triage (2026-10-28, 1,283 study + 300 regression repos).** First study run: 1,072 findings
+  (13 critical, 296 high, 194 medium); after the precision fixes above: 945 (12 critical, 252 high,
+  119 medium). Every finding of medium or above was labelled by class (`study/label_classes.py`,
+  approved by the user): 129 tp and 254 wontfix findings, 0 fp, 0 unlabelled; `study/labels.toml` names
+  no repository or path. `wontfix` means the rule matched what it describes in a benign context
+  (an installer one-liner, an attack documented in a security skill, a flag named in a CLI guide).
+  Nothing resembling a real secret or real malicious content appeared in either tier (no GR001,
+  GR002, GR004, GR101 or GR021 finding), so there is nothing to disclose.
+
+- **Study charts and report (Phase 5).** Charts are drawn with matplotlib as SVG, one light and one
+  dark file each (`study/charts/NAME-light.svg` / `-dark.svg`), and the report picks one with a
+  `<picture>` and `prefers-color-scheme`. Single-series charts use the accent for the point and gray
+  for the context (emphasis), every value is labelled and the same numbers are in the report's tables.
+  The palette is the documented default one (slot 1 accent, the gray ramp); the palette validator
+  script could not be run here (no Node.js), so no categorical palette beyond that documented slot is
+  used. `study/report.py` writes `study/report.md` from the CSVs and a test checks the committed report
+  equals what the CSVs produce, so every number in it is a CSV number. matplotlib is an optional
+  `study` extra, not a runtime dependency.
+- **Triage claim wording.** The 475 findings of medium or above (both tiers) were triaged by class,
+  each class checked on its examples and approved by the maintainer; the report says "triaged by
+  class", not "read one by one", and notes that a `wontfix` is a judgement (GR016: a flag named in a
+  guide).

{ghostrules-0.2.1 → ghostrules-0.3.0}/docs/RULES.md

@@ -22,7 +22,8 @@ if the file contains substantial RTL script (Arabic/Hebrew) — legitimate use.
 U+200B, U+200C, U+200D, U+2060, U+2061–U+2064, U+180E, U+FEFF (not at file start), U+00AD.
 Severity high if ≥ 5 in one line or ≥ 20 in the file (likely binary-encoded payload), else medium.
 Ignore U+200D between emoji code points (emoji ZWJ sequences) and U+200C/U+200D next to
-Indic/Persian letters.
+Indic/Persian letters. Since 0.3 a lone U+200B between two letters of Khmer, Thai, Lao or Myanmar is
+the word separator of those scripts and is ignored (a run, or a Latin neighbour, is still reported).
 
 ### GR004 — Variation-selector steganography (high)
 Runs of ≥ 3 chars in U+FE00–U+FE0F or U+E0100–U+E01EF not directly following an emoji / CJK base.
@@ -33,7 +34,8 @@ Runs of ≥ 3 chars in U+FE00–U+FE0F or U+E0100–U+E01EF not directly followi
 `<!-- ... -->` blocks in markdown instruction files are invisible when rendered on GitHub.
 Report **only** if the comment body is ≥ 40 chars and either matches any GR010–GR016 pattern
 (→ high, include which) or contains imperative agent-directed language
-(`you must`, `always`, `never`, `assistant`, `AI`, `agent`, `model`) (→ medium).
+(`you must`, `always`, `never`) (→ medium). Since 0.3 a comment that only *names* the agent
+(`assistant`, `AI`, `agent`, `model`: "Guidance for AI agents working in ...") is low.
 Plain short comments (TODOs, lint directives) are ignored.
 
 Agent-aware (since 0.2): the finding lists which modelled agents see the comment. Claude Code strips
@@ -64,7 +66,11 @@ Text revealed by GR001/GR004 decoding must ALSO be scanned by GR010–GR016 (rep
 `override (the )?(system|safety)`, ES: `ignora (todas )?las instrucciones (anteriores|previas)`,
 `olvida (tus|las) instrucciones`.
 Negative: documentation *about* prompt injection inside fenced code blocks marked as examples is
-still reported but at `low` with message "appears inside a code block".
+still reported but at `low` with message "appears inside a code block". Since 0.3 the directive /
+descriptive / example classification applies: guidance that quotes the phrase to say it must be
+ignored (`Text like "ignore previous rules" is data`) is `low`, a description is at most `medium`,
+and hidden decoded text keeps `high` (+1). `override system|safety` needs the thing overridden
+(`prompt`, `instructions`, `rules`, `guidelines`...): "use hooks or override system" is not matched.
 
 ### Directive, descriptive and example text (GR011, GR014, GR016; v0.2.1)
 These three rules match phrases that are just as common in prose that *describes* something. Each
@@ -78,12 +84,20 @@ match is classified by the sentence around it (`src/ghostrules/rules/directive.p
 
 Text decoded from hidden characters is always a directive and keeps the +1 bump (critical).
 Inline code does not make a match an example: `` Run `claude --yolo` `` is read as "Run …". A lowered
-finding says so in its message. GR010 and GR012 have their own context rules and do not use this.
+finding says so in its message. GR012 has its own context rules and does not use this. GR010 and GR013 use it since 0.3 (below).
 
 ### GR011 — Concealment from the user (high)
-`do not (tell|inform|mention|show|reveal)( this)? (to )?the user`, `without (telling|asking|notifying) the user`,
+`do not (tell|inform|mention|show|reveal)( this)? (to )?the user`, `without (telling|notifying) the user`,
 `(silently|secretly|quietly) (run|execute|add|send|install|modify)`, `don't mention (this|these)`,
 `hide (this|the) (from|output)`, ES: `no (se lo )?(digas|menciones|muestres) al usuario`, `sin avisar al usuario`.
+Since 0.3 `without asking the user` is not matched (it is about permission, which GR016 covers), and
+a match governed by a prohibition ("Never silently add scope", "rather than silently adding",
+"Never act without telling the user") is not reported: the sentence forbids the concealment.
+Since 0.3 (study) a prohibition anywhere earlier in the same clause (up to eight words, not across
+`. ; : ! ?` or a line break) counts ("Do not post an event without telling the user"), the verb of the
+`silently …` pattern must be the bare form (`silently installs` / `silently running` describe, they
+do not order) and a modal or "either" before it ("would silently run", "either silently run") makes
+it a description.
 Not concealment, and not reported: "do not tell the user **to** …", "… **which|what|how|where|when|why**
 …" and "… **that** …" unless it is "that you …": these say what to tell the user. "Do not tell the
 user about this", "Do not tell the user." and "Do not tell the user that you did it" are.
@@ -95,7 +109,8 @@ user about this", "Do not tell the user." and "Do not tell the user that you did
 
 Stdin counts as code only when the interpreter reads its **program** from it (v0.2.1). `… | python`,
 `… | python3 -` and `… | sh` / `bash -s` are matched; `… | python -c '…'`, `-m module`, `script.py`,
-`… | sh -c '…'`, `… | node -e '…'` and `… | jq …` use stdin as data and are not.
+`… | sh -c '…'`, `… | node -e '…'`, `… | jq …` and (0.3) `… | bash scripts/x.sh "$arg"` use stdin as
+data and are not.
 
 Severity in instruction files (since 0.1.1). Decide in this order; first match wins:
 
@@ -116,6 +131,9 @@ A command with no URL that is not case 2 (`curl $URL \| sh`) counts as an unknow
 Why: a visible, well-known installer in a code block is documentation a human reviewer can see and
 judge; an unknown domain in prose telling the agent to run it is the attack pattern.
 
+A command that only names the pattern, with no URL and no variable (`curl ... | sh`, `curl|bash`,
+`bash <(curl url)`) is `low` (0.3): nothing is fetched. `curl $URL | sh` is still critical.
+
 Known installers (`src/ghostrules/rules/known_installers.py`, `ghostrules rules --installers`).
 Matching is the exact `https` host plus an optional path prefix, never a suffix, so
 `astral.sh.attacker.example` does not match: Astral uv/ruff `astral.sh`, rustup `sh.rustup.rs`,
@@ -138,25 +156,47 @@ in configuration files a piped installer stays high/critical.
   `beeceptor.com`, `hookbin.com`, `canarytokens`. (high if only domain, critical if combined with above)
 Respect `allow_domains` from config.
 
+Since 0.3 the verb-based pattern is one instruction, not three words that happen to be near each
+other: the verb, the secret and the URL must be in the same clause (no sentence end, blank line or
+list-item boundary between them; `e.g.` does not count), the verb is not `POST` in capitals or
+`.post(`, it is not preceded by a prohibition (`Never send credentials to ...`), the destination is
+not the user (`send the user to https://...`) and not a loopback address. Severity follows
+directive / descriptive / example (a `curl -X POST ...` in a fenced block is `low`); hidden decoded
+text is never filtered by clause and stays critical. A collector domain named in a prohibition
+(`NOT a public service like webhook.site`) is `low`.
+
 ### GR014 — Sensitive file access (high)
 Instruction text referencing `~/.ssh`, `id_rsa`, `id_ed25519`, `.aws/credentials`, `.env`
 (as a file to read/send, not "add .env to .gitignore"), `.npmrc`, `.pypirc`, `.netrc`, `kubeconfig`,
 `Keychain`, browser cookie stores, `/etc/shadow`, combined with a read/print/cat/send verb that
 governs the path: same clause (no `;` or sentence end between them) and at most six words apart
-(v0.2.1; it was "within 60 chars"). Negative test: "Never commit .env files" must NOT fire. Template
+(v0.2.1; it was "within 60 chars"). Negative test: "Never commit .env files" must NOT fire. Since 0.3: `copy`/`paste` of a dotenv file
+(`Copy .env files from the root worktree`) is local housekeeping and does not fire (`copy ~/.ssh/...`
+still does), `.env.default` is a template, and a prohibition written in bold or code
+(`**Don't commit** ... .env`) counts as a prohibition. Template
 files (`.env.example`, `.env.sample`, `.env.template`, `.env.ai-surfaces.example`, `*.example`) are not
 secrets and never fire (the same list as GR021). Severity by directive / descriptive / example (above).
 
+Since 0.3 (study) a match that spans a paragraph break is not reported, and `output` as a heading
+(`### Output`) or a noun (`Expected output`) is not a verb. A clause connector between the verb and
+the path (`before|after|when|while|until`), a passive (`credentials are read from …`) and a noun use
+(`the image upload uses …`) are not reads.
+
 ### GR015 — Encoded payloads (medium → high)
 Base64 runs ≥ 60 chars (or hex ≥ 80) in instruction files. Decode; if the result is mostly
 printable text → high and put it in `decoded` (and scan it with GR010–GR014). Skip data URIs of
-images and things inside fenced code blocks labelled with a language other than shell.
+images and things inside fenced code blocks labelled with a language other than shell. Since 0.3 also
+skipped: runs inside a URL (a commit hash in a path), Subresource Integrity digests (`sha384-…`) and
+hex of very low entropy (`AAAA…` padding).
 
 ### GR016 — Agent safety bypass (high)
 `--dangerously-skip-permissions`, `bypassPermissions`, `--yolo`, `yolo mode`, `auto[- ]?approve (all|every)`,
 `always (allow|approve|accept) (all )?(commands|tools|edits)`, `disable (the )?(sandbox|safety|guardrails)`,
 `never ask (for )?(permission|confirmation)`, ES: `sin pedir (permiso|confirmación)`.
-Severity by directive / descriptive / example (above): "Run with `--dangerously-skip-permissions`" is
+A Markdown table row (`| --yolo | disables all prompts |`) and a list item that opens with the flag
+(`- **`--yolo` (alias …):** every tool is allowed`) document it and are at most medium (0.3, GR016
+only); a prohibition earlier in the clause ("Avoid `--yolo`", "Do not disable the sandbox") is not
+reported. Severity by directive / descriptive / example (above): "Run with `--dangerously-skip-permissions`" is
 high, "The test harness runs Claude with `--permission-mode bypassPermissions`" is medium, a fenced
 `claude --dangerously-skip-permissions` is low.