garnet-guard 0.1.0a1__tar.gz

garnet_guard-0.1.0a1/.github/ISSUE_TEMPLATE/false-positive.md

@@ -0,0 +1,13 @@
+---
+name: False positive
+about: Garnet warned or blocked on an update that was fine
+labels: false-positive
+---
+
+**Package and versions:** <!-- e.g. numpy 2.1.0 → 2.1.1 (PyPI) -->
+
+**Finding(s):** <!-- rule IDs and the text Garnet printed -->
+
+**Why it's fine:** <!-- e.g. the project moved its release workflow; link to the announcement -->
+
+**Garnet version and how you ran it:** <!-- CLI / Action, version -->

garnet_guard-0.1.0a1/.github/ISSUE_TEMPLATE/missed-detection.md

@@ -0,0 +1,15 @@
+---
+name: Missed detection
+about: A compromised or suspicious release Garnet didn't flag
+labels: missed-detection
+---
+
+<!-- If this is a novel bypass attackers could use today, report it privately instead (see SECURITY.md). -->
+
+**Package and versions:**
+
+**What was wrong with the release:** <!-- links to write-ups -->
+
+**What Garnet reported:**
+
+**Signal you think should have caught it:**

garnet_guard-0.1.0a1/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: ci
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      dev:
+        dependency-type: development
+    commit-message:
+      prefix: deps

garnet_guard-0.1.0a1/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## What changes
+
+<!-- What a user or reviewer would notice. -->
+
+## Why
+
+<!-- Link the issue. -->
+
+## Sensitive paths touched
+
+<!-- safe_archive.py, action/, workflows, release config, default policy. Write "none" if none. -->
+
+## Rule changes
+
+<!-- For rule changes: IDs affected, fixtures added, backtest warn-rate before → after. Otherwise "n/a". -->
+
+## AI assistance
+
+<!-- Which parts were generated by an agent, if any. -->
+
+## Checklist
+
+- [ ] Tests, ruff and mypy pass locally
+- [ ] No hard rule in AGENTS.md is broken
+- [ ] Commits are signed off (DCO)

garnet_guard-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: Lint and typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: "3.11"
+          enable-cache: false
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src
+      - run: uv run lint-imports
+
+  test:
+    name: Tests (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: false
+      - run: uv sync --locked
+      - run: uv run pytest
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: false
+      - run: uv build --no-sources
+      - name: Smoke-test the built wheel
+        run: uvx --isolated --from dist/*.whl garnet --help

garnet_guard-0.1.0a1/.github/workflows/garnet-guard.yml

@@ -0,0 +1,39 @@
+# Garnet Guard checks this repository's own dependency pull requests, the same
+# way a user's repository would (action/examples/garnet-guard.yml). Dependabot
+# opens a pull request for uv.lock each week (.github/dependabot.yml).
+#
+# The Action is pinned to a commit on main, not run from the pull request
+# (uses: ./). From the pull request it would install Garnet Guard from the
+# pull request's own uv.lock, so the updated packages would run before they
+# were checked. Move the pin forward by hand after the Action changes, and to
+# a release commit once one is tagged.
+name: Garnet Guard
+
+on:
+  pull_request:
+    paths:
+      - "uv.lock"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  garnet-guard:
+    name: Check dependency changes
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read        # read the lockfiles and the base commit
+      pull-requests: write  # post or update the comment
+      security-events: write  # upload the SARIF report to code scanning
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: orca-solutions/garnet-guard@69c8e01d6ad51d7716fb9f9729e87bc2d21eda2b # main, 2026-10-30
+        with:
+          fail-on: block
+          sarif: true

garnet_guard-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Release
+
+# Publishes garnet-guard to PyPI when the maintainer pushes a version tag.
+# Trusted Publishing (OIDC) replaces any stored token, and
+# pypa/gh-action-pypi-publish signs PEP 740 attestations for every file.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    name: CI
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  build:
+    name: Build
+    needs: checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: false
+      - name: Check the tag is on main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::Tag $GITHUB_REF_NAME points at $GITHUB_SHA, which is not on main. Release tags must be cut from main."
+            exit 1
+          fi
+      - name: Check the tag matches the project version
+        run: |
+          version="$(uv version --short)"
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match the version in pyproject.toml ($version). Bump the version in a PR, merge it, then tag v$version."
+            exit 1
+          fi
+      - run: uv build --no-sources
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/garnet-guard/
+    permissions:
+      id-token: write # Trusted Publishing and attestation signing; nothing else
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          attestations: true
+
+  verify:
+    name: Verify attestations on PyPI
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - run: uv sync --locked
+      - name: Verify each published file against this repository
+        run: |
+          for path in dist/*; do
+            file="$(basename "$path")"
+            ok=""
+            for attempt in 1 2 3 4 5 6; do
+              if uv run python -m pypi_attestations verify pypi \
+                  --repository "https://github.com/$GITHUB_REPOSITORY" "pypi:$file"; then
+                ok=1
+                break
+              fi
+              echo "Attestation for $file not verifiable yet (attempt $attempt); retrying in 30s."
+              sleep 30
+            done
+            if [ -z "$ok" ]; then
+              echo "::error::Could not verify the PyPI attestation for $file."
+              exit 1
+            fi
+          done

garnet_guard-0.1.0a1/.github/workflows/scorecard.yml

@@ -0,0 +1,38 @@
+name: OpenSSF Scorecard
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "23 6 * * 1"
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+      security-events: write # upload results to code scanning
+      id-token: write # publish results to the Scorecard API for the badge
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: scorecard-results
+          path: results.sarif
+          retention-days: 5
+      - uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+        with:
+          sarif_file: results.sarif

garnet_guard-0.1.0a1/.gitignore

@@ -0,0 +1,37 @@
+# Maintainer's private operating method; supplied through project instructions, never committed.
+# AGENTS.md and CLAUDE.md are public (Garnet Guard's contributor and agent rules).
+/.claude/
+PR_WORKFLOW.md
+docs/AGENT_ROLES.md
+HANDOFF_TEMPLATES.md
+SOFTWARE_OPERATING_GUIDE.md
+
+# Internal, dated infrastructure inventory; never publish with app source.
+/docs/PLATFORM_SNAPSHOT.md
+
+# Common
+.DS_Store
+node_modules/
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Generated by python -m backtest
+backtest/results.json
+
+# Personal agent overrides stay local; shared entry points remain tracked.
+CLAUDE.local.md

garnet_guard-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.13

garnet_guard-0.1.0a1/AGENTS.md

@@ -0,0 +1,66 @@
+# Garnet Guard: instructions for coding agents
+
+`AGENTS.md` and `CLAUDE.md` are identical copies and must stay identical. Codex reads `AGENTS.md`; Claude Code reads `CLAUDE.md`. If the maintainer's private operating guide (`SOFTWARE_OPERATING_GUIDE.md`, `PR_WORKFLOW.md`, `docs/AGENT_ROLES.md`) is present in your workspace, follow it as well; it is supplied through project instructions, not the repository. Report unavailable guidance instead of claiming it was checked.
+
+## Commands
+
+- Install: `uv sync`
+- Dev server: none (CLI and GitHub Action)
+- Focused tests: `uv run pytest tests/<path> -k <name>`; all unit tests: `uv run pytest` (no network); network tests only when asked: `uv run pytest -m network`
+- Lint / typecheck: `uv run ruff check . && uv run ruff format --check . && uv run mypy src && uv run lint-imports`
+- Build: `uv build`
+- Backtest (required for rule changes): `uv run python -m backtest`
+
+Run tests, ruff and mypy before saying a change is done.
+
+## Start here
+
+Read [PROJECT_BRIEF.md](PROJECT_BRIEF.md) and `WORKING_RECORD.md`, then [ARCHITECTURE.md](ARCHITECTURE.md), [docs/SPEC-v1.md](docs/SPEC-v1.md) and [docs/API.md](docs/API.md) before changing code, and [PRINCIPLES.md](PRINCIPLES.md) when a choice is unclear. Read [THREAT_MODEL.md](THREAT_MODEL.md) before touching anything that reads package contents or runs in CI.
+
+## Project-specific
+
+### What Garnet Guard is
+
+A release-diff guard for dependency updates. It compares a new version of a package against the version a project already trusts and reports trust downgrades, risky content changes and known-bad matches.
+
+### Hard rules
+
+These are not style preferences. A change that breaks one is wrong even if tests pass.
+
+1. **Never execute inspected package code.** No `import`, `exec`, `subprocess`, build backend or install of anything Garnet downloads. Parse with `ast` and read files as bytes.
+2. **All archive access goes through `safe_archive.py`.** Never call `zipfile`/`tarfile` extraction elsewhere.
+3. **Checks are pure.** No I/O in `checks/`. Fetching belongs in `ecosystems/`. Respect the import rules in docs/API.md §2.
+4. **"Couldn't check" is never "pass".** Errors surface as findings or a non-zero exit.
+5. **Escape all package-supplied strings** before they reach markdown, SARIF or a terminal.
+6. **Rule IDs are permanent.** Don't renumber or reuse them.
+7. **No new runtime dependency** without an ADR in `docs/decisions/`. Dev dependencies are fine.
+8. **Unit tests use fixtures, not the network.**
+9. **Never weaken a test, skip a test or lower a backtest threshold to get green.**
+
+### High-risk paths
+
+These are Garnet Guard's high-risk class: changes to them get focused independent review and the maintainer's deliberate review. Call them out at the top of the PR description.
+
+- `src/garnet_guard/safe_archive.py` and `src/garnet_guard/net.py`
+- `action/` and `.github/workflows/`
+- release and publishing configuration
+- default policy and rule severities
+
+Other routine changes are verified by their author.
+
+### How work flows
+
+- Work happens on a branch, one issue per branch, and lands through a pull request. Agents open PRs as drafts; only the maintainer merges.
+- Keep PRs small. If a task grows, stop and propose a split in the PR description.
+- A PR that adds or changes a rule includes positive and negative fixtures, `garnet explain` text and the backtest delta.
+- If a requirement is unclear, leave a question in the PR rather than guessing at behavior users will see.
+- Commits are signed (configured signing) and signed off (`git commit -s`, DCO).
+- **No co-author trailers or "generated by" lines in commits.** The commit-msg hook strips them. Disclose agent use in the PR description's "AI assistance" section instead.
+
+### Style
+
+- **User-facing text** (findings, `explain` text, PR comments, CLI messages) follows the voice rules in docs/brand/brand-kit.md: calm, exact, never "safe", evidence on every line.
+- Python 3.11+, full type hints, `mypy --strict` on `src/`.
+- Dataclasses (frozen) for models. Keep the public API in `garnet_guard/__init__.py` small.
+- Findings must be deterministic: sort output, avoid timestamps in report bodies.
+- Error messages and `explain` text are written for a developer reviewing a dependency PR: say what changed, why it matters, and what to do.

garnet_guard-0.1.0a1/ARCHITECTURE.md

@@ -0,0 +1,158 @@
+# Garnet Guard architecture
+
+This describes the engine Garnet is built around and the surfaces that use it. It is the reference for anyone, human or agent, adding code. Decisions behind it are recorded in [docs/decisions/](docs/decisions/). The exact behavior is specified in [docs/SPEC-v1.md](docs/SPEC-v1.md) and the code design in [docs/API.md](docs/API.md); where they differ from this overview, they win.
+
+## Shape in one picture
+
+```text
+ lockfile (base)  ─┐
+                   ├─► LockfileDiff ─► [ReleasePair, ...]
+ lockfile (head)  ─┘                          │
+                                              ▼
+                              Ecosystem adapter (pypi, npm)
+                         metadata · artifacts · provenance · tags
+                                   (content-addressed cache)
+                                              │
+                                              ▼
+                          ReleaseFacts(old)   ReleaseFacts(new)
+                                              │
+                                              ▼
+                     Checks: trust · content · known-bad  ─►  [Finding, ...]
+                                              │
+                                              ▼
+                               Policy (garnet.toml) ─► Verdict
+                                              │
+                                              ▼
+                 Reporters: text · JSON · SARIF · PR comment markdown
+                                              │
+              ┌───────────────────────┬───────┴──────────────┐
+              ▼                       ▼                      ▼
+        GitHub Action           CLI (garnet check)     Agent / install hooks
+          (month 2)               (month 1)                (month 3)
+```
+
+Every surface is a thin shell over one library call: `garnet_guard.evaluate(diff, policy) -> Report`.
+
+## Core concepts
+
+**ReleasePair.** One dependency changing: ecosystem, package name, `old` version (the baseline you trusted) and `new` version. A newly added dependency has no `old`; it gets only known-bad and absolute checks, not diff checks.
+
+**Baseline.** In the open-source tool the baseline is simply the version in the base lockfile, i.e. the version this project already runs. If an update skips versions (2.6.1 → 2.6.4), Garnet diffs against 2.6.1 and also reports trust signals for each skipped release, since a compromise can hide in the middle. In v2 the engine also computes **per-package history from the registry** (how the last N releases were published), so the baseline isn't limited to one release; that stays in the free engine (ADR-0009). The hosted app adds what only a service can see: history observed across many organizations.
+
+**ReleaseFacts.** Everything Garnet knows about one release, extracted once and cached:
+
+- registry metadata (upload time, uploader, yanked status, files and hashes)
+- provenance per file (attestation present, Sigstore identity, source repo, workflow, ref, Trusted Publishing yes/no)
+- source link (repository URL, whether a matching git tag exists and which commit it points to)
+- content inventory per artifact (file list, sizes, hashes, file types, `.pth` files, entry points, build backend, install scripts for npm)
+- a static index of Python modules: top-level statements per module, imports, and calls to sensitive APIs
+
+**Check.** A pure function over two `ReleaseFacts` that returns findings. Checks do no I/O; adapters fetch, checks judge. That makes every check unit-testable from fixtures.
+
+```python
+class Check(Protocol):
+    id: str                      # stable rule ID, e.g. "GRN-T001"
+    ecosystems: frozenset[str]   # {"pypi"}, {"npm"} or both
+    def run(self, pair: ReleasePair, old: ReleaseFacts | None,
+            new: ReleaseFacts) -> list[Finding]: ...
+```
+
+**Finding.** `rule_id`, `severity` (info / warn / block), `package`, `old`, `new`, `title`, `evidence` (list of file path + line, URL, or attestation field), `explanation` and `remediation`. Findings must be deterministic for the same inputs so PR comments don't churn.
+
+**Policy.** `garnet.toml` (or `[tool.garnet]` in `pyproject.toml`) maps rules to severities and holds allow-lists:
+
+```toml
+[garnet]
+default = "warn"               # warn | block
+
+[garnet.rules]
+GRN-T001 = "block"             # lost provenance
+GRN-C004 = "off"               # new binaries are normal for us
+
+[[garnet.ignore]]
+package = "numpy"
+rules = ["GRN-C004"]
+reason = "ships compiled wheels"
+until = "2027-06-30"           # ignores expire
+```
+
+**Verdict.** The worst severity across findings after policy: `pass`, `warn` or `block`. Exit codes: 0 pass, 1 warn (only when `--fail-on warn`), 2 block, 3 Garnet error.
+
+## Ecosystem adapters
+
+Each ecosystem implements one interface, so checks and reporters never touch registry specifics:
+
+```python
+class Ecosystem(Protocol):
+    name: str
+    def parse_lockfile(self, path: Path) -> dict[str, str]: ...      # name -> version
+    def release_facts(self, name: str, version: str) -> ReleaseFacts: ...
+```
+
+**PyPI (month 1).** JSON API for metadata and files, the Integrity API (`/integrity/<project>/<version>/<filename>/provenance`) for PEP 740 attestations, verified with the `pypi-attestations` library. Wheels and the sdist are both inspected, because sdists carry build code. Lockfile parsers: uv.lock, poetry.lock, pylock.toml, pinned requirements.txt with hashes.
+
+**npm (month 2).** Registry packument and tarball, npm provenance / Sigstore attestations, `scripts` and `bin` from `package.json`. Lockfile parsers: package-lock.json, pnpm-lock.yaml, yarn.lock.
+
+**Source host.** Tag lookups go to the repository named by provenance first, falling back to project URLs in metadata. GitHub only at first, through the public API with an optional token for rate limits.
+
+## Initial rule catalog
+
+IDs are stable forever. A retired rule keeps its ID reserved. Exact firing conditions and default severities are in SPEC §6.
+
+| ID | Rule | Signal |
+|---|---|---|
+| GRN-T001 | lost-provenance | Old release had an attestation; new one has none. |
+| GRN-T002 | publisher-changed | Attested source repository changed. |
+| GRN-T003 | workflow-changed | Same repo, different publishing workflow file or environment. |
+| GRN-T004 | no-matching-tag | No git tag for the new version in the attested or declared repo. |
+| GRN-T005 | outside-trusted-publishing | Old files came through Trusted Publishing; new ones were uploaded with a token. |
+| GRN-T006 | files-uploaded-late | A file was added to a release long after the release was first published. |
+| GRN-C001 | new-pth-file | A `.pth` file appears that the old release didn't have. |
+| GRN-C002 | new-build-hook | New `setup.py` logic, custom build backend, or new npm install-time script. |
+| GRN-C003 | new-import-time-exec | New module-level calls to `exec`, `eval`, `compile`, `subprocess`, `os.system`, `ctypes`, sockets or HTTP clients. |
+| GRN-C004 | new-binary | New native binaries or executables not explained by the build (e.g. outside the platform wheel's normal extension modules). |
+| GRN-C005 | obfuscated-blob | New long base64/hex/compressed literals, especially passed to exec or decode. |
+| GRN-C006 | sdist-wheel-mismatch | Wheel contains files with no counterpart in the sdist. |
+| GRN-C007 | code-not-in-source | A Python file in the release isn't the one at its git tag and has sensitive calls the source lacks (code injected by the build, as in ultralytics 8.3.42). |
+| GRN-T007 | invalid-attestation | An attestation exists but fails verification (blocks by default). |
+| GRN-T008 | hash-mismatch | A download doesn't match the registry's published hash (blocks by default). |
+| GRN-K001 | known-malicious | OSV `MAL-` advisory for this package version. |
+| GRN-E001–E005 | couldn't-check | Fetch, parse or budget failures, unpinned or unsupported sources. Reported, never silently passed. |
+
+Heuristic content rules run **only on files that changed** between the two releases. That is the main lever on false positives. GuardDog's Semgrep/YARA rules are a useful reference for patterns, with their licenses respected.
+
+## Safety of the engine itself
+
+Garnet handles hostile input by design. These are invariants, enforced in code review and tests:
+
+- **No execution.** Nothing from an inspected package is ever imported, run, built or installed. Python source is parsed with `ast` only.
+- **Safe extraction.** Archives are read in memory or into a private temp dir with limits on total size, file count, compression ratio and path depth. Absolute paths, `..` segments, symlinks, hard links and device files are rejected.
+- **Bounded work.** Timeouts on every network call, and a per-package budget; on a budget overrun Garnet reports an error finding rather than silently passing.
+- **Fail visible.** If Garnet can't fetch or verify something, it says so in the report. It never turns "couldn't check" into "pass".
+
+See [THREAT_MODEL.md](THREAT_MODEL.md) for the full analysis.
+
+## Caching and determinism
+
+Artifacts and facts are cached by content hash under the user cache dir (and `actions/cache` in CI). Facts for a given `(ecosystem, name, version)` are immutable once a release is published, except for yanks and late file uploads, which are re-checked. Outputs sort findings deterministically.
+
+## Surfaces
+
+**CLI.** `garnet check --base <lockfile> --head <lockfile>`, `garnet explain <rule>`, `garnet diff <pkg> <old> <new>`. Run with `uvx garnet-guard` or install with `uv tool install garnet-guard`.
+
+**GitHub Action (month 2).** Runs on `pull_request` when a lockfile changes, compares the base and head lockfiles, and posts or updates one sticky comment plus an optional SARIF upload. Design constraints:
+
+- Never use `pull_request_target` with a checkout of PR code.
+- Least privilege: `contents: read`, and `pull-requests: write` only in the step that comments.
+- Dependabot-triggered runs get a restricted token. If commenting directly isn't possible, use the two-workflow pattern: the analysis job uploads the report as an artifact, and a `workflow_run` job with write permission posts it without checking out PR code. *Verify current GitHub behavior before building.*
+- The Action is pinned by commit SHA in all docs, and its own dependencies are hash-locked.
+
+**Install wrapper and agent hooks (month 3).** `garnet pip install …` / `garnet uv sync` resolve first, run `evaluate` on the resulting change, then hand off to the real tool. Claude Code and Codex hooks call the same entry point before a dependency is added.
+
+## Package layout
+
+See [docs/API.md](docs/API.md) §9 for the full layout and §2 for the import rules between layers. The distribution is `garnet-guard` and the import package is `garnet_guard` (ADR-0007). The CLI command is `garnet`.
+
+## Backtesting
+
+`backtest/` replays known incidents (47 malicious releases of 36 compromised PyPI packages, listed in `backtest/incidents.toml`, and four npm account takeovers in `backtest/npm-incidents.toml`) and a clean corpus of recent releases of the top ~500 PyPI packages. Every rule change runs against it. Two numbers gate releases: detection on the incident set and warn rate on the clean corpus. Where an incident's malicious artifacts were removed from the registry, the replay uses recorded `ReleaseFacts` from public write-ups rather than the files.