ARPAHLS · rosspeili · Aug 21, 2026 · Aug 21, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,37 @@
+# PR and main-branch CI — lint and test only (no secrets, no PyPI OIDC).
+# Keep install/lint/test steps in sync with publish-pypi.yml test job until issue #7
+# (reusable workflow) lands.
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: black
+        run: black --check aura tests
+      - name: flake8
+        run: flake8 aura tests
+      - name: pytest
+        run: pytest
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -21,6 +21,7 @@ permissions:
   contents: read
 
 jobs:
+  # Steps must match .github/workflows/ci.yml lint-test job (see docs/TESTING.md).
   test:
     runs-on: ubuntu-latest
     steps:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **PR CI workflow** ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) — `lint-test` job on pull requests and pushes to `main` (black, flake8, pytest); read-only permissions, no PyPI secrets.
+
 ## [0.3.2] - 2026-08-20
 
 ### Changed

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -127,7 +127,7 @@ Follow the [Code of Conduct](CODE_OF_CONDUCT.md). We welcome autonomous logical
   flake8 aura tests
   ```
 
-- CI runs on PRs: tests, black, flake8 (see [publish-pypi.yml](.github/workflows/publish-pypi.yml) test job pattern).
+- CI runs on PRs via [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (job **`lint-test`**: pytest, black, flake8). See [TESTING.md](docs/TESTING.md).
 - Wait for green checks before requesting review.
 
 ### CHANGELOG
@@ -155,6 +155,7 @@ Pure internal refactors with no user-visible effect may omit CHANGELOG; ask on t
 | New example | `examples/README.md`, optional link from `docs/getting-started.md` |
 | Architecture terminology | `docs/architecture.md`, `README.md` diagrams (keep in sync) |
 | Release / PyPI behavior | `docs/PUBLISHING.md`, `.github/workflows/publish-pypi.yml`, CHANGELOG |
+| PR CI workflow | `.github/workflows/ci.yml`, `docs/TESTING.md`, `CONTRIBUTING.md`; keep publish test job in sync |
 | Issue template fields | `.github/labels.json` if new label needed; run label sync |
 | Version (maintainer only) | `pyproject.toml`, `aura/__init__.py`, `CITATION.cff`, CHANGELOG release section, Zenodo if archived |
 

diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md
@@ -7,7 +7,7 @@ Releases are published automatically by [`.github/workflows/publish-pypi.yml`](.
 
 Pushing a `v*` tag alone does **not** publish; create and publish the GitHub Release from that tag.
 
-The workflow runs tests, builds sdist/wheel, then uploads to PyPI.
+The workflow runs tests, builds sdist/wheel, then uploads to PyPI. **Pull requests** are gated separately by [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (`lint-test` on every PR to `main`).
 
 ## One-time PyPI setup
 

diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -24,6 +24,28 @@ flake8 aura tests
 
 CI expectation: **pytest**, **black**, and **flake8** all pass on `aura/` and `tests/`.
 
+## Continuous integration
+
+GitHub Actions workflow **[`.github/workflows/ci.yml`](../.github/workflows/ci.yml)** (job name: **`lint-test`**) runs on:
+
+- every **pull request** targeting `main`
+- every **push** to `main` (post-merge sanity)
+
+Steps (Python 3.12 on Ubuntu):
+
+```bash
+pip install -e ".[dev]"
+black --check aura tests
+flake8 aura tests
+pytest
+```
+
+**Fork PRs:** the workflow uses `permissions: contents: read` only — no repository secrets, no PyPI OIDC, no deploy environment.
+
+**Publish workflow:** [`.github/workflows/publish-pypi.yml`](../.github/workflows/publish-pypi.yml) runs the same lint/test steps before release upload; keep both in sync until a reusable workflow lands (separate CI follow-up issue).
+
+**Maintainers:** after the first green `lint-test` run on `main`, enable **branch protection** → required status check **`lint-test`**.
+
 ## What we test
 
 | Area | Tests |

diff --git a/docs/contributing/ai_native_workflow.md b/docs/contributing/ai_native_workflow.md
@@ -41,6 +41,7 @@ Written for **autonomous and semi-autonomous agents** working on AURA Harness. H
 - [ ] `pytest` passes
 - [ ] `black aura tests` — no diff
 - [ ] `flake8 aura tests` — clean
+- [ ] CI green — [`lint-test`](../../.github/workflows/ci.yml) job on the PR
 - [ ] Tests added/updated for behavior changes
 - [ ] [CHANGELOG.md](../../CHANGELOG.md) updated under `[Unreleased]` when user-visible
 - [ ] Docs/examples updated per [ripple table](../../CONTRIBUTING.md#ripple-effects-if-you-change-x-update-y)
-Original file line number
+Diff line change
@@ Expand Up / @@ -21,6 +21,7 @@ permissions: @@
       contents: read
     jobs:
+      # Steps must match .github/workflows/ci.yml lint-test job (see docs/TESTING.md).
       test:
         runs-on: ubuntu-latest
         steps:
@@ Expand Down @@