floe-python 0.8.9__tar.gz → 0.10.0__tar.gz

floe_python-0.10.0/.github/workflows/airflow-floe.yml

@@ -0,0 +1,41 @@
+name: Airflow Floe (Python)
+
+on:
+  pull_request:
+    paths:
+      - "orchestrators/airflow-floe/**"
+      - "orchestrators/dagster-floe/src/floe_dagster/databricks_client.py"
+      - "orchestrators/dagster-floe/src/floe_dagster/k8s_status.py"
+      - ".github/workflows/airflow-floe.yml"
+  push:
+    branches: ["main"]
+    paths:
+      - "orchestrators/airflow-floe/**"
+      - "orchestrators/dagster-floe/src/floe_dagster/databricks_client.py"
+      - "orchestrators/dagster-floe/src/floe_dagster/k8s_status.py"
+      - ".github/workflows/airflow-floe.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Syntax check
+        run: python -m compileall orchestrators/airflow-floe/src orchestrators/airflow-floe/dags orchestrators/airflow-floe/tests
+      - name: Package install check
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install orchestrators/airflow-floe --no-deps
+      - name: Tests
+        run: python -m unittest discover -s orchestrators/airflow-floe/tests -p "test_*.py"

floe_python-0.10.0/.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: CI
+
+on:
+  pull_request:
+  merge_group:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # Single source of truth for path-based change detection. Runs `paths-filter`
+  # once and exposes every flag as a job output so the jobs below can gate at the
+  # job level (via `needs` + `if`) instead of each re-running checkout +
+  # paths-filter and booting a runner only to skip its steps.
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      config_schema: ${{ steps.filter.outputs.config_schema }}
+      docs: ${{ steps.filter.outputs.docs }}
+      python_core: ${{ steps.filter.outputs.python_core }}
+      conformance: ${{ steps.filter.outputs.conformance }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dorny/paths-filter@v4
+        id: filter
+        with:
+          filters: |
+            config_schema:
+              - "schemas/**"
+              - "scripts/test_config_schema.py"
+              - "src/floe/config/**"
+              - "src/floe/pii.py"
+              - "pyproject.toml"
+              - "uv.lock"
+              - "example/project/**"
+              - "example/standalone/**"
+              - ".github/workflows/ci.yml"
+            docs:
+              - "docs/**"
+              - "README.md"
+            python_core:
+              - "src/floe/**"
+              - "tests/**"
+              - "conformance/**"
+              - "orchestrators/dagster-floe/**"
+              - "orchestrators/airflow-floe/**"
+              - "pyproject.toml"
+              - "uv.lock"
+              - ".github/workflows/ci.yml"
+            conformance:
+              - "conformance/**"
+              - "src/floe/**"
+              - "pyproject.toml"
+              - "uv.lock"
+              - ".github/workflows/ci.yml"
+
+  config-schema:
+    needs: changes
+    if: needs.changes.outputs.config_schema == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - run: uv run python scripts/test_config_schema.py
+
+  python-lint:
+    needs: changes
+    if: needs.changes.outputs.python_core == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  python-types:
+    needs: changes
+    if: needs.changes.outputs.python_core == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - run: uv run pyright
+      # dagster-floe is checked in basic mode (its own pyrightconfig.json) against the real dagster types
+      - run: uv pip install -e "orchestrators/dagster-floe[kubernetes]"
+      - run: uv run --no-sync pyright -p orchestrators/dagster-floe
+      # airflow-floe likewise; installing apache-airflow takes about 10 s, so pyright sees the real Airflow types
+      - run: uv pip install -e orchestrators/airflow-floe
+      - run: uv run --no-sync pyright -p orchestrators/airflow-floe
+
+  python-test:
+    needs: changes
+    # Gated per step, not per job: a skipped matrix job reports one `python-test`
+    # check, so the required `python-test (<version>)` checks would never report.
+    runs-on: ubuntu-latest
+    timeout-minutes: 20  # a stalled download or source build fails fast instead of hanging for GitHub's 6 h default
+    strategy:
+      fail-fast: false
+      matrix:
+        # Oldest supported (`requires-python`) and the newest with a wheel for every locked
+        # package. 3.15 builds duckdb, numpy, pyiceberg, pyyaml and zstandard from source;
+        # move up once they ship cp315 wheels.
+        python-version: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+        if: needs.changes.outputs.python_core == 'true'
+      - uses: astral-sh/setup-uv@v7
+        if: needs.changes.outputs.python_core == 'true'
+      - run: uv sync --all-groups --all-extras --python ${{ matrix.python-version }}
+        if: needs.changes.outputs.python_core == 'true'
+      - run: uv run --python ${{ matrix.python-version }} pytest --cov=floe
+        if: needs.changes.outputs.python_core == 'true'
+
+  core-only:
+    # No extras: a local CSV to Parquet run must work with the core dependencies alone.
+    needs: changes
+    if: needs.changes.outputs.python_core == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv venv --python 3.11 "$RUNNER_TEMP/core" && uv pip install --python "$RUNNER_TEMP/core" .
+      - run: |
+          cp -r example/standalone "$RUNNER_TEMP/work"
+          cd "$RUNNER_TEMP/work"
+          "$RUNNER_TEMP/core/bin/floe" validate -c config.yml
+          "$RUNNER_TEMP/core/bin/floe" run -c config.yml
+          test -f out/accepted/orders/part-00000.parquet
+
+  golden:
+    # The branch ruleset requires the check named `conformance`.
+    name: conformance
+    needs: changes
+    if: needs.changes.outputs.conformance == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - name: Python matches every golden case
+        run: uv run python conformance/check.py
+

floe_python-0.10.0/.github/workflows/coverage-python.yml

@@ -0,0 +1,46 @@
+name: Coverage (Python)
+
+# Informational only — never make this a required check. Runs on main after
+# Python core changes, on demand, and on PRs that edit this file.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/floe/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/coverage-python.yml"
+  pull_request:
+    paths:
+      - ".github/workflows/coverage-python.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  coverage-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - name: Measure floe coverage
+        # Explicit bash turns on pipefail so a test failure isn't masked by tee.
+        shell: bash
+        run: uv run pytest --cov=floe --cov-report=term | tee coverage.txt
+      - name: Publish summary
+        run: |
+          {
+            echo '## floe (Python) coverage'
+            echo '```'
+            grep '^TOTAL' coverage.txt
+            echo '```'
+            echo '<details><summary>Per file</summary>'
+            echo
+            echo '```'
+            cat coverage.txt
+            echo '```'
+            echo '</details>'
+          } >> "$GITHUB_STEP_SUMMARY"

floe_python-0.10.0/.github/workflows/dagster-floe.yml

@@ -0,0 +1,47 @@
+name: Dagster Floe (Python)
+
+on:
+  pull_request:
+    paths:
+      - "orchestrators/dagster-floe/**"
+      - "orchestrators/schemas/**"
+      - "src/floe/**"
+      - "pyproject.toml"
+      - ".github/workflows/dagster-floe.yml"
+  push:
+    branches: ["main"]
+    paths:
+      - "orchestrators/dagster-floe/**"
+      - "orchestrators/schemas/**"
+      - "src/floe/**"
+      - "pyproject.toml"
+      - ".github/workflows/dagster-floe.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            orchestrators/dagster-floe/pyproject.toml
+            pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all]"  # the floe core from this checkout: config mode needs floe.build_manifest
+          python -m pip install -e "orchestrators/dagster-floe[dev]"
+      - name: Tests
+        run: |
+          python -m pytest -q orchestrators/dagster-floe/tests

floe_python-0.10.0/.github/workflows/python-integration.yml

@@ -0,0 +1,120 @@
+name: Python integration (Polaris)
+
+# Also nightly: the `glue` tests against moto, the `perf` memory test (#1063) and the 200-entity `scale` suite (#558),
+# whose 10-entity Iceberg subset runs in the `polaris` job below.
+# Runs the `polaris` and `s3` marked tests against the #602 harness (Polaris + SeaweedFS).
+# Not a required check yet (#840): the maintainer makes it required once it is stable.
+on:
+  pull_request:
+    paths:
+      - "src/floe/iceberg/**"
+      - "src/floe/storage/**"
+      - "src/floe/run/**"
+      - "tests/integration/**"
+      - ".github/workflows/python-integration.yml"
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  polaris:
+    runs-on: ubuntu-latest
+    env:
+      FLOE_POLARIS_URI: http://localhost:8181/api/catalog
+      FLOE_S3_ENDPOINT: http://localhost:8333
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      # Same images, credentials and settings as spikes/python/harness/docker-compose.yml (#602).
+      - name: Start SeaweedFS and Polaris
+        run: |
+          docker network create harness
+          docker run -d --name seaweedfs --network harness -p 8333:8333 \
+            -e AWS_ACCESS_KEY_ID=spike -e AWS_SECRET_ACCESS_KEY=spike-s3-secret \
+            chrislusf/seaweedfs:4.48@sha256:4e61d15fd35994cb1e43e1e553dff106794841fd9a99ade2fc8c8bfce4d7872d \
+            mini -dir=/data -bucket=warehouse
+          # 403 without credentials means S3 is up and auth is on.
+          timeout 120 sh -c 'until [ "$(curl -s -o /dev/null -w "%{http_code}" localhost:8333/warehouse)" = 403 ]; do sleep 2; done'
+          docker run -d --name polaris --network harness -p 8181:8181 -p 8182:8182 \
+            -e AWS_REGION=us-east-1 -e AWS_ACCESS_KEY_ID=spike -e AWS_SECRET_ACCESS_KEY=spike-s3-secret \
+            -e POLARIS_BOOTSTRAP_CREDENTIALS=POLARIS,root,s3cr3t \
+            -e polaris.realm-context.realms=POLARIS -e quarkus.otel.sdk.disabled=true \
+            apache/polaris:1.8.0@sha256:347615e736cab2c9be0d8c464552ac930be4755302bb0aeb745216bbae99ba5b
+          timeout 180 sh -c 'until curl -sf localhost:8182/q/health; do sleep 2; done'
+      # Same steps as spikes/python/harness/bootstrap.py (#602), on a fresh in-memory Polaris.
+      - name: Bootstrap catalog, principal and grants
+        run: |
+          token() {
+            curl -sS --fail-with-body localhost:8181/api/catalog/v1/oauth/tokens \
+              -d grant_type=client_credentials -d client_id="$1" -d client_secret="$2" \
+              -d scope=PRINCIPAL_ROLE:ALL | jq -r .access_token
+          }
+          api() {
+            curl -sS --fail-with-body -X "$1" "localhost:8181/api$2" \
+              -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d "$3"
+            echo
+          }
+          TOKEN=$(token root s3cr3t)
+          api POST /management/v1/catalogs '{"catalog": {"name": "spike", "type": "INTERNAL",
+            "properties": {"default-base-location": "s3://warehouse/spike"},
+            "storageConfigInfo": {"storageType": "S3", "allowedLocations": ["s3://warehouse"],
+              "endpoint": "http://localhost:8333", "endpointInternal": "http://seaweedfs:8333",
+              "pathStyleAccess": true, "region": "us-east-1", "stsUnavailable": true}}}'
+          api POST /management/v1/principals '{"principal": {"name": "spike"}}'
+          api POST /management/v1/principals/spike/reset '{"clientId": "spike-client", "clientSecret": "spike-secret"}'
+          api POST /management/v1/principal-roles '{"principalRole": {"name": "spike_role"}}'
+          api PUT /management/v1/principals/spike/principal-roles '{"principalRole": {"name": "spike_role"}}'
+          api PUT /management/v1/principal-roles/spike_role/catalog-roles/spike '{"catalogRole": {"name": "catalog_admin"}}'
+          api PUT /management/v1/catalogs/spike/catalog-roles/catalog_admin/grants '{"grant": {"type": "catalog", "privilege": "CATALOG_MANAGE_CONTENT"}}'
+          # As the new principal: checks its credentials and grants.
+          TOKEN=$(token spike-client spike-secret)
+          api POST /catalog/v1/spike/namespaces '{"namespace": ["spike"]}'
+      - run: uv run pytest -m "polaris or s3" -rs tests/integration
+      - name: Scale subset on Polaris
+        if: github.event_name != 'pull_request'
+        run: uv run pytest -m "polaris and scale" -rs tests/scale
+      - name: Container logs
+        if: failure()
+        run: |
+          docker logs seaweedfs
+          docker logs polaris
+
+  # Nightly and on demand only: Glue (moto) and the memory regression need no harness.
+  glue:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    env:
+      FLOE_GLUE_ENDPOINT: http://localhost:5055
+      FLOE_S3_ENDPOINT: http://localhost:5055
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      # moto serves Glue and S3 on one port; its own tool environment keeps it out of the project's lockfile
+      - name: Start moto
+        run: |
+          uvx --from "moto[server]==5.2.5" moto_server -p 5055 > moto.log 2>&1 &
+          timeout 60 sh -c 'until curl -s localhost:5055 >/dev/null; do sleep 1; done'
+      - run: uv run pytest -m glue -rs tests/integration
+      - name: Moto log
+        if: failure()
+        run: cat moto.log
+
+  perf:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --all-groups --all-extras
+      - run: uv run pytest -m perf tests/perf
+      # the run summary (runtime, startup, peak RSS per step) is in the log: -rP prints it
+      - run: uv run pytest -m "scale and not polaris" -rP tests/scale

floe_python-0.10.0/AGENTS.md

@@ -0,0 +1,157 @@
+# AGENTS.md — rules for anyone (human or AI) changing Floe
+
+These rules are not suggestions. A PR that breaks one gets closed, not fixed up.
+The goal: **the smallest correct change, one concern per PR, nothing speculative.**
+
+## 1. Read the context you need — and only that
+
+| Read | When |
+|---|---|
+| `context/project.md` | First time in the repo: what Floe is and is not |
+| `context/architecture.md` | Before touching `src/floe/` |
+| `context/coding-standards.md` | Before writing Python |
+| `context/testing-strategy.md` | Before writing or moving tests or golden cases (`conformance/`) |
+| `context/decisions/python-core-for-olf.md` | Before changing Iceberg writes, merges, memory bounds or the scope of supported features |
+| `context/orchestrators.md` | Before touching `orchestrators/` |
+| `context/bump-release.md` | Version bump and release PRs only |
+| `context/decisions/*.md` | Before changing incremental state, commit/retry guarantees, or Polars/Arrow usage |
+
+## 2. Ponytail is mandatory
+
+- **Claude Code:** install the plugin once (`/plugin marketplace add DietrichGebert/ponytail`,
+  then `/plugin install ponytail@ponytail`) and work in `full` mode. Before opening a PR, run
+  `/ponytail-review` on your diff and resolve every finding, or justify it in the PR body.
+- **Other agents** apply the same ladder. Stop at the first rung that holds:
+  1. Does this need to exist at all? If not, skip it and say so.
+  2. Does it already exist in this codebase? Reuse it. Grep before you write.
+  3. Does the Python stdlib do it?
+  4. Does a dependency we already have do it? Never add one for a few lines.
+  5. Can it be one line?
+  6. Only then: the minimum code that works.
+- Mark deliberate shortcuts that have a known ceiling with a `ponytail:` comment naming the
+  ceiling and the upgrade path.
+- The ladder shortens the solution, never the reading. Understand the flow before picking a rung.
+
+## 3. Hard rules
+
+**Scope**
+- One issue → one branch → one PR. Never bundle issues (#427 fixed three at once; don't).
+- Noticed an unrelated bug or smell? Open an issue. Do not fix it in this PR.
+- `fix:` PRs add no new CLI flag, config field, manifest field or public API. That is a `feat:`
+  and gets its own issue (#444 was a "fix" that added `--runtime`; don't).
+- Version bumps, dependency bumps and schema resyncs each get their own PR.
+
+**Size** (enforced by `.github/workflows/pr-size.yml`)
+- Budget: **≤ 300 changed lines and ≤ 8 files** of non-test code under `src/floe/` and
+  `orchestrators/`. Tests, fixtures, docs, CHANGELOG, lockfiles and JSON schemas don't count.
+- Over budget? Split it into stacked PRs: a behaviour-neutral prep PR (move, extract, rename)
+  first, then the behaviour change on top.
+- Only a maintainer may apply the `large-pr` label. Agents never apply it.
+
+**Diff hygiene**
+- Read before you write: trace the real flow end to end, and grep every caller of a function
+  before changing it. Fix the root cause in the shared function, not the symptom in one caller.
+- No drive-by refactors, renames, reformatting, comment rewrites or "while I'm here" edits in
+  code the change does not need.
+- No new dependency without approval on the issue first.
+- No new trait, Protocol or ABC, generic, builder, registry or config knob until three concrete
+  uses exist. A new module is fine when it holds one self-contained concern.
+- Never hand-edit a vendored copy. Edit the canonical file (`orchestrators/schemas/`, or the
+  dagster copy of a shared module) and the connector tests confirm
+  the copies match (`orchestrators/airflow-floe/tests/test_vendored_copies.py`,
+  `orchestrators/dagster-floe/tests/test_vendored_schema.py`).
+- No `# noqa`, `# type: ignore` or `# pyright: ignore` without an inline reason.
+
+**Tests**
+- Every bug fix ships one test that fails without the fix.
+- Every new behaviour ships the test listed for its change type in `context/testing-strategy.md`.
+- Don't write tests for code you didn't change.
+
+**Git**
+- Never commit to `main`. Never force-push a branch you did not create.
+- Use conventional commit titles: `fix(scope):`, `feat(scope):`, `docs:`, `ci:`, `chore:`.
+
+## 4. Stop and ask instead of guessing
+
+Ask on the issue, or ask the user, before writing code when:
+- the issue is ambiguous, or the fix could go in more than one place;
+- the change touches the config YAML schema or the manifest format (both are user contracts);
+- it needs a new dependency;
+- it would go over the size budget and you can't see a clean split.
+
+## 5. Checks before every push
+
+These mirror `.github/workflows/ci.yml`. All must pass. Floe is a `uv` project, Python >= 3.11.
+
+```bash
+uv sync --all-groups
+uv run ruff check
+uv run ruff format --check
+uv run pyright                                          # strict
+uv run pytest
+uv run python conformance/check.py                      # golden suite
+```
+
+If `orchestrators/<connector>/` changed, also run that connector's tests as its workflow does
+(`.github/workflows/dagster-floe.yml`, `airflow-floe.yml`).
+
+## 6. PR body
+
+Use `.github/PULL_REQUEST_TEMPLATE.md`. It must state:
+- the issue it serves: `Closes #N`, or `Part of #N` for a PR that is one step of a stack (CI checks size only, not the body);
+- why this is the minimum change;
+- what you deliberately did not do;
+- the `/ponytail-review` result (or "ladder applied" for non-Claude agents);
+- the commands you ran.
+
+Update `CHANGELOG.md` and `docs/` only when the change is user-visible.
+
+## 7. Non-goals
+
+Settled scope, not gaps. A change or review finding that asks for one of these is closed with a
+pointer here, not implemented.
+
+| Not a goal | Why |
+|---|---|
+| Streaming or continuous processing | Floe ingests files and batch extracts. Kafka-style sources belong to a streaming engine. |
+| Transformations (SQL, joins, models) | Floe validates and routes rows. Shaping them is dbt's job downstream. |
+| Distributed execution or worker coordination | One process, one machine. Concurrent runs coordinate only through the CAS incremental state (`context/decisions/incremental-state-cas.md`). No locks, leases or queues beyond it. |
+
+## 8. Agent workflow
+
+Work flows milestone → parent issue → sub-issues. **A sub-issue is one PR**: it fits the §3
+budget, names the files it touches, and says which test must fail first. One that can't is split
+before anyone writes code.
+
+1. **Plan.** The planner (a maintainer or the CTO agent) writes sub-issues from the Task template,
+   with `file:line` references it has verified, and links them to the parent.
+2. **Build.** One developer agent per sub-issue, in its own git worktree, on a branch named
+   `<type>/<issue>-<slug>`. Read the issue in full (`gh issue view <n>`): its references beat any
+   summary. Then §1–§5.
+3. **Open.** PR body per §6 with `Closes #<sub-issue>`, then comment `@codex review`.
+4. **Review loop.** Fix every P0/P1 finding. Fix a P2 only if it is in scope and small; otherwise
+   reply with why. Push, resolve the threads you addressed, and ask for review again. Out-of-scope
+   findings get a new issue, a reply linking it, and a resolved thread.
+5. **Done** when Codex has reviewed the latest commit with no P0/P1 findings and every thread is
+   resolved.
+6. **Three rounds, then stop.** If round three still raises a P0/P1, do not push a fourth fix.
+   Comment on the sub-issue what keeps coming back; the planner re-scopes or splits it. Repeated
+   P1s mean the issue was mis-scoped, not that the code needs another patch.
+7. **Merge.** The planner runs `gh pr merge --auto --squash`. The merge queue re-tests against
+   `main`, so never update a branch from `main` by hand. Merge stacked PRs bottom-up; squashing
+   the top first folds the whole stack into one commit.
+
+## 9. Review guidelines
+
+For Codex and any other reviewer. Review the diff against its linked issue: the issue's scope and
+out-of-scope lists are the contract.
+
+- **P0:** data loss or corrupted output; rows accepted that the contract rejects, or the reverse;
+  a security hole or leaked secret.
+- **P1:** wrong behaviour in the changed code; a break in the config YAML, manifest or run report
+  contract; a bug fix without a test that fails without it; a §3 hard-rule violation.
+- **P2 at most:** naming, style, comments, docs wording, possible refactors, and edge cases with
+  no concrete input that triggers them.
+- **Do not flag:** pre-existing problems in code the diff does not change (suggest an issue);
+  anything in §7; missing abstractions; defensive checks for states the code already rules out.
+- A P0/P1 names the concrete input or state that triggers it. If you can't name one, it is a P2.