From f5bc2f0d912dd4b657b146ee8dfb413662f0376d Mon Sep 17 00:00:00 2001 From: pkuwkl Date: Tue, 14 Jul 2026 21:44:04 +0800 Subject: [PATCH 1/2] ci: consolidate deterministic CI and live E2E workflows --- .agents/skills/quantmind-dev/SKILL.md | 13 +++--- .claude/skills/quantmind-dev/SKILL.md | 13 +++--- .github/workflows/{verify.yml => ci.yml} | 21 ++++++---- .github/workflows/{news-e2e.yml => e2e.yml} | 17 +++++++- .github/workflows/pre-commit.yml | 46 --------------------- AGENTS.md | 17 ++++---- CLAUDE.md | 17 ++++---- CONTRIBUTING.md | 23 +++++++---- docs/README.md | 22 ++++++---- scripts/verify.sh | 3 +- 10 files changed, 95 insertions(+), 97 deletions(-) rename .github/workflows/{verify.yml => ci.yml} (64%) rename .github/workflows/{news-e2e.yml => e2e.yml} (61%) delete mode 100644 .github/workflows/pre-commit.yml diff --git a/.agents/skills/quantmind-dev/SKILL.md b/.agents/skills/quantmind-dev/SKILL.md index 4b0cda8..af80c5a 100644 --- a/.agents/skills/quantmind-dev/SKILL.md +++ b/.agents/skills/quantmind-dev/SKILL.md @@ -26,11 +26,14 @@ A feature task usually chains all three: develop → commit → pull request. ## Rules -- `bash scripts/verify.sh` is the deterministic offline golden gate. Run it - before every push and before marking a PR ready. -- Public-network integrations have separate bounded live component gates. - Run every applicable gate listed in `docs/README.md` when changing that - component and before publishing. +- `bash scripts/verify.sh` is the deterministic required verification. Run it + before every push and before marking a PR ready. The required + `.github/workflows/ci.yml` workflow runs the same harness. +- Public-network integrations have separate bounded smoke tests. + `.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered + component jobs. Run every applicable test listed in `docs/README.md` when + changing that component and before publishing. External service availability + must not block unrelated changes. - Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user explicitly authorizes it. - New features ship with a unit test and a focused example (see diff --git a/.claude/skills/quantmind-dev/SKILL.md b/.claude/skills/quantmind-dev/SKILL.md index 4b0cda8..af80c5a 100644 --- a/.claude/skills/quantmind-dev/SKILL.md +++ b/.claude/skills/quantmind-dev/SKILL.md @@ -26,11 +26,14 @@ A feature task usually chains all three: develop → commit → pull request. ## Rules -- `bash scripts/verify.sh` is the deterministic offline golden gate. Run it - before every push and before marking a PR ready. -- Public-network integrations have separate bounded live component gates. - Run every applicable gate listed in `docs/README.md` when changing that - component and before publishing. +- `bash scripts/verify.sh` is the deterministic required verification. Run it + before every push and before marking a PR ready. The required + `.github/workflows/ci.yml` workflow runs the same harness. +- Public-network integrations have separate bounded smoke tests. + `.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered + component jobs. Run every applicable test listed in `docs/README.md` when + changing that component and before publishing. External service availability + must not block unrelated changes. - Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user explicitly authorizes it. - New features ship with a unit test and a focused example (see diff --git a/.github/workflows/verify.yml b/.github/workflows/ci.yml similarity index 64% rename from .github/workflows/verify.yml rename to .github/workflows/ci.yml index 321fbc7..58766e6 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: verify +name: ci on: pull_request: @@ -7,15 +7,17 @@ on: branches: [master] workflow_dispatch: -# Cancel in-progress runs on the same PR/branch when a new commit lands. +permissions: + contents: read + concurrency: - group: verify-${{ github.workflow }}-${{ github.ref }} + group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: - verify: + ci: runs-on: ubuntu-latest - timeout-minutes: 15 + timeout-minutes: 20 steps: - name: Checkout @@ -35,10 +37,13 @@ jobs: - name: Create virtual environment run: uv venv - - name: Install project + dev dependencies + - name: Install project and development dependencies run: uv pip install --python .venv/bin/python -e ".[dev]" - - name: Run scripts/verify.sh + - name: Run file-hygiene hooks run: | source .venv/bin/activate - bash scripts/verify.sh + SKIP=ruff,ruff-format pre-commit run --all-files --hook-stage pre-commit + + - name: Run deterministic verification + run: bash scripts/verify.sh diff --git a/.github/workflows/news-e2e.yml b/.github/workflows/e2e.yml similarity index 61% rename from .github/workflows/news-e2e.yml rename to .github/workflows/e2e.yml index 567db07..f37551c 100644 --- a/.github/workflows/news-e2e.yml +++ b/.github/workflows/e2e.yml @@ -1,8 +1,21 @@ -name: news-e2e +name: e2e on: pull_request: branches: [master] + paths: + - '.github/workflows/e2e.yml' + - 'scripts/verify_news_e2e.py' + - 'quantmind/preprocess/_news_types.py' + - 'quantmind/preprocess/clean.py' + - 'quantmind/preprocess/news.py' + - 'quantmind/preprocess/pr_newswire.py' + - 'quantmind/preprocess/time.py' + - 'quantmind/preprocess/format/html.py' + - 'quantmind/preprocess/fetch/__init__.py' + - 'quantmind/preprocess/fetch/_types.py' + - 'quantmind/preprocess/fetch/http.py' + - 'quantmind/preprocess/fetch/rss.py' schedule: - cron: "17 3 * * *" workflow_dispatch: @@ -15,7 +28,7 @@ concurrency: cancel-in-progress: true jobs: - news-e2e: + news: runs-on: ubuntu-latest timeout-minutes: 10 diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml deleted file mode 100644 index 89de772..0000000 --- a/.github/workflows/pre-commit.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: pre-commit - -# Runs the pre-commit-stage hooks defined in .pre-commit-config.yaml as a -# CI safety net for contributors who skip local hooks. File-hygiene checks -# (trailing whitespace, EOF, yaml, large files, merge conflicts) and ruff -# format/lint live here. The verify loop (basedpyright, import-linter, -# pytest --cov) runs in verify.yml; the two workflows are orthogonal. - -on: - pull_request: - branches: [master] - push: - branches: [master] - workflow_dispatch: - -concurrency: - group: pre-commit-${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -jobs: - pre-commit: - runs-on: ubuntu-latest - timeout-minutes: 10 - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.10' - - - name: Cache pre-commit - uses: actions/cache@v4 - with: - path: ~/.cache/pre-commit - key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }} - - - name: Install pre-commit - run: | - python -m pip install --upgrade pip - pip install pre-commit - - - name: Run pre-commit hooks (commit stage) - run: pre-commit run --all-files --hook-stage pre-commit diff --git a/AGENTS.md b/AGENTS.md index d1b0d79..8060fd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,17 +31,20 @@ resurrect it into master. ```bash uv venv && source .venv/bin/activate uv pip install -e ".[dev]" -bash scripts/verify.sh # deterministic offline golden gate -python scripts/verify_news_e2e.py # live PR Newswire component gate +bash scripts/verify.sh # deterministic required verification +python scripts/verify_news_e2e.py # live-network news smoke test ``` `scripts/verify.sh` runs five fast-fail steps (`ruff format --check`, `ruff check`, `basedpyright`, `lint-imports`, `pytest --cov`) and must remain -network-free. Public-network integrations have separate bounded live gates; -run each applicable gate when changing that component and before publishing. -The current component catalog and commands live in `docs/README.md`. Do not -bypass pre-commit / pre-push hooks unless the user explicitly authorizes it — -fix the underlying issue instead. +network-free. `.github/workflows/ci.yml` is the required deterministic CI +workflow. Public-network integrations have separate bounded smoke tests; +`.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered +component jobs. Run each applicable smoke test when changing that component +and before publishing. External PR Newswire availability must not block +unrelated changes. The component catalog and commands live in `docs/README.md`. +Do not bypass pre-commit / pre-push hooks unless the user explicitly authorizes +it — fix the underlying issue instead. ## Architecture Constraints (stable) diff --git a/CLAUDE.md b/CLAUDE.md index b5c66d2..0f7a326 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,17 +32,20 @@ resurrect it into master. ```bash uv venv && source .venv/bin/activate uv pip install -e ".[dev]" -bash scripts/verify.sh # deterministic offline golden gate -python scripts/verify_news_e2e.py # live PR Newswire component gate +bash scripts/verify.sh # deterministic required verification +python scripts/verify_news_e2e.py # live-network news smoke test ``` `scripts/verify.sh` runs five fast-fail steps (`ruff format --check`, `ruff check`, `basedpyright`, `lint-imports`, `pytest --cov`) and must remain -network-free. Public-network integrations have separate bounded live gates; -run each applicable gate when changing that component and before publishing. -The current component catalog and commands live in `docs/README.md`. Do not -bypass pre-commit / pre-push hooks unless the user explicitly authorizes it — -fix the underlying issue instead. +network-free. `.github/workflows/ci.yml` is the required deterministic CI +workflow. Public-network integrations have separate bounded smoke tests; +`.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered +component jobs. Run each applicable smoke test when changing that component +and before publishing. External PR Newswire availability must not block +unrelated changes. The component catalog and commands live in `docs/README.md`. +Do not bypass pre-commit / pre-push hooks unless the user explicitly authorizes +it — fix the underlying issue instead. ## Architecture Constraints (stable) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3e787a..d7d02a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ will pick these up automatically. ## ✅ Verification -`scripts/verify.sh` is the deterministic offline golden gate for every PR: +`scripts/verify.sh` is the deterministic required verification for every PR: ```bash bash scripts/verify.sh @@ -34,17 +34,24 @@ bash scripts/verify.sh It runs five fast-fail steps: `ruff format --check`, `ruff check`, `basedpyright`, `lint-imports`, `pytest --cov` (with a branch-coverage -floor configured in `pyproject.toml`). It stays network-free. +floor configured in `pyproject.toml`). It stays network-free, and the required +`.github/workflows/ci.yml` workflow runs the same harness after file-hygiene +hooks. -Public-network integrations have separate bounded live component gates. -Run every applicable gate when changing that component and before publishing; -the current commands are listed in [`docs/README.md`](docs/README.md). For -example, PR Newswire uses: +Public-network integrations have separate bounded live component smoke tests. +`.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered +jobs. Run every applicable test when changing that component and before +publishing; the current commands are listed in +[`docs/README.md`](docs/README.md). For example, PR Newswire uses: ```bash python scripts/verify_news_e2e.py ``` +This command uses the real public network. External PR Newswire availability +must not block unrelated changes, so the E2E workflow only runs for relevant +pull-request paths and is not a required merge check. + **Hooks**: the pre-commit stage runs formatting/lint and file hygiene checks; the pre-push stage runs the full `scripts/verify.sh`. If a hook fails, fix the issue — don't bypass with `--no-verify`. @@ -82,8 +89,8 @@ pytest tests// 1. **Create a feature branch** from `master`. 2. **Follow Conventional Commits**: `type(scope): description`, in English. -3. **Verify before submitting**: the offline golden gate and every applicable - live component gate must be green. +3. **Verify before submitting**: deterministic verification and every + applicable live-network component smoke test must be green. 4. **Submit the PR** using the template — English body, reference the related issue, and state the verification you performed. 5. Keep PRs small and focused diff --git a/docs/README.md b/docs/README.md index 757ab4b..3e0d289 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,29 +24,35 @@ layer shown in the catalog. ## Public-Network Sources -| Source | Source selection | Operation | Live component gate | +| Source | Source selection | Operation | Live-network component smoke test | |---|---|---|---| | PR Newswire | `NewsWindow(source="pr-newswire", ...)` | `collect_news` | `python scripts/verify_news_e2e.py` | -The PR Newswire gate checks the public RSS feed and a complete preceding -24-hour listing window without fetching article pages. Its GitHub workflow -runs on pull requests, daily, and on manual dispatch. +The PR Newswire smoke test checks the public RSS feed and a complete preceding +24-hour listing window without fetching article pages. It depends on the real +public network. The `news` job in `.github/workflows/e2e.yml` runs daily, on +manual dispatch, and only on pull requests that change its dependency paths. +It is not a required merge check, so external PR Newswire availability cannot +block unrelated changes. ## Verification -Run the deterministic offline golden gate for every change: +Run the deterministic required verification for every change: ```bash bash scripts/verify.sh ``` It covers formatting, linting, typing, import boundaries, unit tests, and -coverage, and must remain network-free. When a change affects a public-network -component, also run every applicable live gate listed above. +coverage, and must remain network-free. The required `.github/workflows/ci.yml` +workflow runs this same harness after file-hygiene hooks. When a change affects +a public-network component, also run every applicable live-network smoke test +listed above; `.github/workflows/e2e.yml` owns those component jobs. ## Adding a Public Operation or Source Use the `quantmind-dev` component workflow. A public operation is not complete until its typed contract, package exports, offline tests, focused example, design or guide, and catalog row agree. A public-network source additionally -needs mocked source tests plus a bounded live verifier and CI workflow. +needs mocked source tests plus a bounded live verifier and component job in +`.github/workflows/e2e.yml`. diff --git a/scripts/verify.sh b/scripts/verify.sh index a7b5a7a..ce75c04 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -1,7 +1,8 @@ #!/usr/bin/env bash # QuantMind Golden Harness — single command, fast-fail verify loop. # -# Run before pushing; CI runs the same script (.github/workflows/verify.yml). +# Run before pushing; required CI runs the same script +# (.github/workflows/ci.yml). # Steps execute in order; the first failure stops the loop. # # Steps: From dc1ba0112ec3bb18b0e39f0c2c83cfc5e7cf5f11 Mon Sep 17 00:00:00 2001 From: pkuwkl Date: Tue, 14 Jul 2026 22:11:43 +0800 Subject: [PATCH 2/2] docs(ci): document scalable live E2E extensions --- .agents/skills/quantmind-dev/SKILL.md | 6 ++++++ .../skills/quantmind-dev/references/commit.md | 3 ++- .../references/develop-components.md | 17 ++++++++++++----- .../quantmind-dev/references/pull-request.md | 15 ++++++++------- .claude/skills/quantmind-dev/SKILL.md | 6 ++++++ .../skills/quantmind-dev/references/commit.md | 3 ++- .../references/develop-components.md | 17 ++++++++++++----- .../quantmind-dev/references/pull-request.md | 15 ++++++++------- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- .pre-commit-config.yaml | 2 +- AGENTS.md | 16 +++++++++++----- CLAUDE.md | 16 +++++++++++----- docs/README.md | 8 ++++++++ docs/design/en/news.md | 19 +++++++++++-------- scripts/verify.sh | 2 +- 15 files changed, 101 insertions(+), 48 deletions(-) diff --git a/.agents/skills/quantmind-dev/SKILL.md b/.agents/skills/quantmind-dev/SKILL.md index af80c5a..3365f3c 100644 --- a/.agents/skills/quantmind-dev/SKILL.md +++ b/.agents/skills/quantmind-dev/SKILL.md @@ -34,6 +34,12 @@ A feature task usually chains all three: develop → commit → pull request. component jobs. Run every applicable test listed in `docs/README.md` when changing that component and before publishing. External service availability must not block unrelated changes. +- Keep `docs/README.md` as the single catalog of component smoke-test commands. + A new live component adds a component-specific + `scripts/verify__e2e.py`, a named job in the existing `e2e.yml`, + precise PR path coverage, and one catalog row. When multiple live jobs exist, + use GitHub-native per-job change detection so only affected jobs run. Do not + add a separate workflow, generic E2E runner or registry, or base E2E class. - Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user explicitly authorizes it. - New features ship with a unit test and a focused example (see diff --git a/.agents/skills/quantmind-dev/references/commit.md b/.agents/skills/quantmind-dev/references/commit.md index 32737e9..c6e12de 100644 --- a/.agents/skills/quantmind-dev/references/commit.md +++ b/.agents/skills/quantmind-dev/references/commit.md @@ -45,7 +45,8 @@ Do not mix mechanical reformatting with behavior changes. 2. Run verification appropriate to the change: - during development: targeted tests, e.g. `pytest tests//` - - before push / handoff: `bash scripts/verify.sh` (canonical gate) + - before push / handoff: `bash scripts/verify.sh` (deterministic required + verification) 3. Commit. Pre-commit hooks run ruff format/check and file hygiene checks; the pre-push hook runs the full `scripts/verify.sh`. diff --git a/.agents/skills/quantmind-dev/references/develop-components.md b/.agents/skills/quantmind-dev/references/develop-components.md index 88ddf66..7783585 100644 --- a/.agents/skills/quantmind-dev/references/develop-components.md +++ b/.agents/skills/quantmind-dev/references/develop-components.md @@ -21,9 +21,9 @@ apply throughout. 5. **Update the public surface** if needed: package exports, the relevant design or guide, and the catalog in `docs/README.md`. Update the root README only when its overview or quick start changes. -6. **Verify**: run targeted tests while iterating, the offline golden gate - before handoff, and every applicable live component gate for changed - public-network integrations. +6. **Verify**: run targeted tests while iterating, deterministic required + verification before handoff, and every applicable live-network component + smoke test for changed public-network integrations. ## Module Routing @@ -108,8 +108,15 @@ When adding a source to an existing operation: 3. Add offline mocked tests for parsing, boundaries, continuation after item failures, and completeness semantics. 4. Update the source table and design under `docs/`. -5. Add or update a bounded live verifier and GitHub workflow. Keep live - network work out of `scripts/verify.sh`. +5. Add or update a component-specific + `scripts/verify__e2e.py` and list its command in + `docs/README.md`. +6. Add or update the component's named job in the existing + `.github/workflows/e2e.yml` and extend the workflow's precise pull-request + path filter. When multiple live jobs exist, use GitHub-native per-job change + detection so only affected component jobs run. Do not add a separate + workflow, generic runner or registry, or base E2E class. Keep live network + work out of `scripts/verify.sh`. ## Tests diff --git a/.agents/skills/quantmind-dev/references/pull-request.md b/.agents/skills/quantmind-dev/references/pull-request.md index 9c79ac1..36f4231 100644 --- a/.agents/skills/quantmind-dev/references/pull-request.md +++ b/.agents/skills/quantmind-dev/references/pull-request.md @@ -7,16 +7,17 @@ How to open and maintain a pull request against QuantMind. 1. Branch from `master`; keep the PR small and focused — one PR equals one reviewable change (see [Google eng practices on small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)). -2. Run the deterministic offline golden gate: +2. Run the deterministic required verification: ```bash bash scripts/verify.sh ``` 3. If the change affects a public-network integration, run every applicable - live component gate listed in `docs/README.md`. + live-network component smoke test listed in `docs/README.md`. -Do not open or mark ready a PR with a red offline or applicable live gate. +Do not open or mark ready a PR with red deterministic verification or an +applicable red live-network smoke test. ## Title @@ -39,10 +40,10 @@ and make sure the body covers: if one exists. 2. **Related issue** — reference it when one exists (`Closes #NN` / `Part of #NN`). -3. **Verification performed** — state the exact offline and applicable live - commands you ran (e.g. `bash scripts/verify.sh`; targeted - `pytest tests//`; a component verifier; manual example run) so the - reviewer does not have to guess. +3. **Verification performed** — state the exact deterministic and applicable + live-network commands you ran (e.g. `bash scripts/verify.sh`; targeted + `pytest tests//`; a component-specific verifier; manual example + run) so the reviewer does not have to guess. Keep the template checklist and remove items that do not apply. diff --git a/.claude/skills/quantmind-dev/SKILL.md b/.claude/skills/quantmind-dev/SKILL.md index af80c5a..3365f3c 100644 --- a/.claude/skills/quantmind-dev/SKILL.md +++ b/.claude/skills/quantmind-dev/SKILL.md @@ -34,6 +34,12 @@ A feature task usually chains all three: develop → commit → pull request. component jobs. Run every applicable test listed in `docs/README.md` when changing that component and before publishing. External service availability must not block unrelated changes. +- Keep `docs/README.md` as the single catalog of component smoke-test commands. + A new live component adds a component-specific + `scripts/verify__e2e.py`, a named job in the existing `e2e.yml`, + precise PR path coverage, and one catalog row. When multiple live jobs exist, + use GitHub-native per-job change detection so only affected jobs run. Do not + add a separate workflow, generic E2E runner or registry, or base E2E class. - Never bypass pre-commit / pre-push hooks (`--no-verify`) unless the user explicitly authorizes it. - New features ship with a unit test and a focused example (see diff --git a/.claude/skills/quantmind-dev/references/commit.md b/.claude/skills/quantmind-dev/references/commit.md index 32737e9..c6e12de 100644 --- a/.claude/skills/quantmind-dev/references/commit.md +++ b/.claude/skills/quantmind-dev/references/commit.md @@ -45,7 +45,8 @@ Do not mix mechanical reformatting with behavior changes. 2. Run verification appropriate to the change: - during development: targeted tests, e.g. `pytest tests//` - - before push / handoff: `bash scripts/verify.sh` (canonical gate) + - before push / handoff: `bash scripts/verify.sh` (deterministic required + verification) 3. Commit. Pre-commit hooks run ruff format/check and file hygiene checks; the pre-push hook runs the full `scripts/verify.sh`. diff --git a/.claude/skills/quantmind-dev/references/develop-components.md b/.claude/skills/quantmind-dev/references/develop-components.md index 88ddf66..7783585 100644 --- a/.claude/skills/quantmind-dev/references/develop-components.md +++ b/.claude/skills/quantmind-dev/references/develop-components.md @@ -21,9 +21,9 @@ apply throughout. 5. **Update the public surface** if needed: package exports, the relevant design or guide, and the catalog in `docs/README.md`. Update the root README only when its overview or quick start changes. -6. **Verify**: run targeted tests while iterating, the offline golden gate - before handoff, and every applicable live component gate for changed - public-network integrations. +6. **Verify**: run targeted tests while iterating, deterministic required + verification before handoff, and every applicable live-network component + smoke test for changed public-network integrations. ## Module Routing @@ -108,8 +108,15 @@ When adding a source to an existing operation: 3. Add offline mocked tests for parsing, boundaries, continuation after item failures, and completeness semantics. 4. Update the source table and design under `docs/`. -5. Add or update a bounded live verifier and GitHub workflow. Keep live - network work out of `scripts/verify.sh`. +5. Add or update a component-specific + `scripts/verify__e2e.py` and list its command in + `docs/README.md`. +6. Add or update the component's named job in the existing + `.github/workflows/e2e.yml` and extend the workflow's precise pull-request + path filter. When multiple live jobs exist, use GitHub-native per-job change + detection so only affected component jobs run. Do not add a separate + workflow, generic runner or registry, or base E2E class. Keep live network + work out of `scripts/verify.sh`. ## Tests diff --git a/.claude/skills/quantmind-dev/references/pull-request.md b/.claude/skills/quantmind-dev/references/pull-request.md index 9c79ac1..36f4231 100644 --- a/.claude/skills/quantmind-dev/references/pull-request.md +++ b/.claude/skills/quantmind-dev/references/pull-request.md @@ -7,16 +7,17 @@ How to open and maintain a pull request against QuantMind. 1. Branch from `master`; keep the PR small and focused — one PR equals one reviewable change (see [Google eng practices on small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)). -2. Run the deterministic offline golden gate: +2. Run the deterministic required verification: ```bash bash scripts/verify.sh ``` 3. If the change affects a public-network integration, run every applicable - live component gate listed in `docs/README.md`. + live-network component smoke test listed in `docs/README.md`. -Do not open or mark ready a PR with a red offline or applicable live gate. +Do not open or mark ready a PR with red deterministic verification or an +applicable red live-network smoke test. ## Title @@ -39,10 +40,10 @@ and make sure the body covers: if one exists. 2. **Related issue** — reference it when one exists (`Closes #NN` / `Part of #NN`). -3. **Verification performed** — state the exact offline and applicable live - commands you ran (e.g. `bash scripts/verify.sh`; targeted - `pytest tests//`; a component verifier; manual example run) so the - reviewer does not have to guess. +3. **Verification performed** — state the exact deterministic and applicable + live-network commands you ran (e.g. `bash scripts/verify.sh`; targeted + `pytest tests//`; a component-specific verifier; manual example + run) so the reviewer does not have to guess. Keep the template checklist and remove items that do not apply. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a6e8f58..6c2f1ee 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,13 +8,13 @@ ## Verification - + ## Checklist - [ ] The title uses English Conventional Commit format: `type(scope): summary`. - [ ] The related issue or design discussion is linked when applicable. - [ ] `bash scripts/verify.sh` passes. -- [ ] Every applicable live component gate passes, or this PR states why none applies. +- [ ] Every applicable live-network component smoke test passes, or this PR states why none applies. - [ ] Public behavior has focused tests, an example, and documentation where applicable. - [ ] The PR is complete, small, and contains no unrelated changes. diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7bfcf42..486aa30 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,7 +19,7 @@ repos: - repo: local hooks: - id: verify - name: Run scripts/verify.sh (full golden harness) + name: Run scripts/verify.sh (deterministic verification harness) entry: bash scripts/verify.sh language: system pass_filenames: false diff --git a/AGENTS.md b/AGENTS.md index 8060fd9..354cbc7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,6 @@ resurrect it into master. uv venv && source .venv/bin/activate uv pip install -e ".[dev]" bash scripts/verify.sh # deterministic required verification -python scripts/verify_news_e2e.py # live-network news smoke test ``` `scripts/verify.sh` runs five fast-fail steps (`ruff format --check`, @@ -41,10 +40,17 @@ network-free. `.github/workflows/ci.yml` is the required deterministic CI workflow. Public-network integrations have separate bounded smoke tests; `.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered component jobs. Run each applicable smoke test when changing that component -and before publishing. External PR Newswire availability must not block -unrelated changes. The component catalog and commands live in `docs/README.md`. -Do not bypass pre-commit / pre-push hooks unless the user explicitly authorizes -it — fix the underlying issue instead. +and before publishing. External service availability must not block changes +outside that component. `docs/README.md` is the single catalog of component +commands; do not enumerate them in this file. + +To extend live verification, add a component-specific +`scripts/verify__e2e.py`, add a named job to the existing `e2e.yml`, +extend its precise PR path filter, and add one catalog row. When a second live +job is added, use GitHub-native per-job change detection so PRs run only the +affected component jobs. Do not add another E2E workflow, a generic runner or +registry, or a base E2E class. Do not bypass pre-commit / pre-push hooks unless +the user explicitly authorizes it — fix the underlying issue instead. ## Architecture Constraints (stable) diff --git a/CLAUDE.md b/CLAUDE.md index 0f7a326..160d66e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,7 +33,6 @@ resurrect it into master. uv venv && source .venv/bin/activate uv pip install -e ".[dev]" bash scripts/verify.sh # deterministic required verification -python scripts/verify_news_e2e.py # live-network news smoke test ``` `scripts/verify.sh` runs five fast-fail steps (`ruff format --check`, @@ -42,10 +41,17 @@ network-free. `.github/workflows/ci.yml` is the required deterministic CI workflow. Public-network integrations have separate bounded smoke tests; `.github/workflows/e2e.yml` owns their scheduled, manual, and path-filtered component jobs. Run each applicable smoke test when changing that component -and before publishing. External PR Newswire availability must not block -unrelated changes. The component catalog and commands live in `docs/README.md`. -Do not bypass pre-commit / pre-push hooks unless the user explicitly authorizes -it — fix the underlying issue instead. +and before publishing. External service availability must not block changes +outside that component. `docs/README.md` is the single catalog of component +commands; do not enumerate them in this file. + +To extend live verification, add a component-specific +`scripts/verify__e2e.py`, add a named job to the existing `e2e.yml`, +extend its precise PR path filter, and add one catalog row. When a second live +job is added, use GitHub-native per-job change detection so PRs run only the +affected component jobs. Do not add another E2E workflow, a generic runner or +registry, or a base E2E class. Do not bypass pre-commit / pre-push hooks unless +the user explicitly authorizes it — fix the underlying issue instead. ## Architecture Constraints (stable) diff --git a/docs/README.md b/docs/README.md index 3e0d289..bc7d9c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -56,3 +56,11 @@ until its typed contract, package exports, offline tests, focused example, design or guide, and catalog row agree. A public-network source additionally needs mocked source tests plus a bounded live verifier and component job in `.github/workflows/e2e.yml`. + +Each live component owns one `scripts/verify__e2e.py` command and +one named job in the existing `e2e.yml`. Extend the workflow's precise PR path +filter for the component. When multiple live jobs exist, use GitHub-native +per-job change detection so only affected component jobs run. Add commands only +to the catalog above; root agent guidance stays component-neutral. Do not +create a workflow per component or a generic E2E runner, registry, or base +class. diff --git a/docs/design/en/news.md b/docs/design/en/news.md index 269a967..57f61cd 100644 --- a/docs/design/en/news.md +++ b/docs/design/en/news.md @@ -194,7 +194,7 @@ to this OSS library. Verification has two intentionally separate layers. -### Offline verification +### Deterministic verification `bash scripts/verify.sh` runs deterministic unit tests, linting, typing, and coverage. News tests use saved HTML/RSS fixtures and mocked HTTP responses. @@ -203,8 +203,8 @@ observations, raw-byte retention, retries, partial failures, and completeness. ### Live news E2E -`python scripts/verify_news_e2e.py` is the canonical public-network component -check. It performs two bounded checks: +`python scripts/verify_news_e2e.py` is the component-specific live-network news +smoke test. It performs two bounded checks: 1. fetch and parse the official PR Newswire RSS feed; 2. discover PR Newswire listing observations for the preceding 24 hours and @@ -216,9 +216,10 @@ RSS is empty or invalid, listing discovery is empty or incomplete, or a component raises. This keeps the check lightweight while detecting public source or parser drift. -GitHub Actions runs this check on every pull request, once daily, and on manual -dispatch. The ordinary offline verification workflow remains network-free so -local development and unit tests stay deterministic. +The `news` job in `.github/workflows/e2e.yml` runs this check once daily, on +manual dispatch, and on pull requests that change its precise dependency paths. +The required `.github/workflows/ci.yml` workflow remains network-free so local +development and unit tests stay deterministic. ## Non-Goals and Extension Rule @@ -244,8 +245,10 @@ A coding agent adding a second source follows this closed checklist: 5. Add a routing test proving only the selected collector is called. 6. Update the supported-source table in `docs/README.md`, this design, and the focused example if its common path changes. -7. Add or extend a bounded live component verifier and GitHub workflow when - the integration depends on a public network endpoint. +7. Add or extend a component-specific live verifier and its named job in the + existing `.github/workflows/e2e.yml` when the integration depends on a + public network endpoint. Add its command to `docs/README.md`; do not add the + command to root agent guidance. Only after two real collectors expose shared behavior should a common `Protocol` be considered. A new source must never be added only to the input diff --git a/scripts/verify.sh b/scripts/verify.sh index ce75c04..646d82a 100755 --- a/scripts/verify.sh +++ b/scripts/verify.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# QuantMind Golden Harness — single command, fast-fail verify loop. +# QuantMind Deterministic Verification Harness — single fast-fail command. # # Run before pushing; required CI runs the same script # (.github/workflows/ci.yml).