From d4ad6dce9f36a403d4c44f24d7cc2a6662f3b702 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 14 May 2026 07:09:43 +0000 Subject: [PATCH] chore: tighten AI-check Exclusions after 2-week advisory run Addresses five recurring false-positive patterns surfaced across PRs #129, #131, #133, and #134 during the first ~2 weeks of the self-hosted AI checks workflow (introduced in PR #122). https://claude.ai/code/session_01TWxW11tGiSwySi3gCvZk8L --- .ai-checks/branching-and-pr-strategy.md | 13 +++++++++++++ .ai-checks/comment-discipline.md | 4 ++++ .ai-checks/env-var-sync.md | 8 ++++++++ .ai-checks/feature-pr-docs.md | 4 ++++ .ai-checks/pipeline-step-sync.md | 14 ++++++++++++++ 5 files changed, 43 insertions(+) diff --git a/.ai-checks/branching-and-pr-strategy.md b/.ai-checks/branching-and-pr-strategy.md index d613021..46bb740 100644 --- a/.ai-checks/branching-and-pr-strategy.md +++ b/.ai-checks/branching-and-pr-strategy.md @@ -108,3 +108,16 @@ a destructive operation and the human must do it. confirm it was rebase-merged. - Initial repo bootstrap commits (before the rules existed). Use judgement on the date of the violation. +- **GitHub Actions synthetic merge commit.** `actions/checkout@v4` + checks out `refs/pull/N/merge` — a two-parent commit GitHub creates + for CI with a message of the form `Merge ... into ...`. + This commit is NOT part of the PR author's branch; it exists only on + the runner. If the only merge-shaped commit you can see is the + top-of-tree HEAD with that exact message pattern, the branch is + rebased cleanly and you must pass this check. Only flag merge commits + that appear *within* the PR's own commit list (i.e. authored before + the synthetic HEAD). +- **Do not infer the source branch from the PR title, description, or + diff content.** Read the branch name from explicit metadata (e.g. + `head.ref` in the diff context). If that information is absent, do + not assume the PR came from `main`. diff --git a/.ai-checks/comment-discipline.md b/.ai-checks/comment-discipline.md index dec9f5f..ddd8cc1 100644 --- a/.ai-checks/comment-discipline.md +++ b/.ai-checks/comment-discipline.md @@ -105,3 +105,7 @@ Apply across the diff. Especially noisy areas historically: - Tests, where descriptive `# Given / # When / # Then` comments can improve readability — judgement call, lean permissive. - Generated code / migrations. +- **Lines removed by this PR.** A line shown in the diff with a `-` + prefix is being *deleted*. Do not flag removed lines as violations — + they are already gone. Evaluate only lines that are added (`+` + prefix) or present in unchanged context. diff --git a/.ai-checks/env-var-sync.md b/.ai-checks/env-var-sync.md index ab7c762..365ec47 100644 --- a/.ai-checks/env-var-sync.md +++ b/.ai-checks/env-var-sync.md @@ -72,3 +72,11 @@ key, even a revoked one. Flag any commit that adds a value matching - Internal feature flags that are intentionally undocumented (rare; require a comment in code explaining why). - Test-only env vars set in `tests/` and never read by production code. +- **Django model field names, method parameters, and Python attribute + names are not environment variables.** Only flag lines where code + explicitly reads from the process environment: `os.getenv(...)`, + `os.environ[...]`, `os.environ.get(...)`, `settings.RAGTIME_*`, or + equivalent runtime env reads. A Django model field named `show_name` + has no connection to a hypothetical `RAGTIME_SHOW_NAME` env var — do + not invent env var names from field or variable names you see in the + diff. diff --git a/.ai-checks/feature-pr-docs.md b/.ai-checks/feature-pr-docs.md index 7dc431a..7ec4ad7 100644 --- a/.ai-checks/feature-pr-docs.md +++ b/.ai-checks/feature-pr-docs.md @@ -136,3 +136,7 @@ prompt) satisfies this check; summarized/paraphrased content does not. - Bug fixes, refactors, dependency bumps, doc-only PRs. - Hot-fixes explicitly tagged as urgent in the PR description (note as follow-up debt, don't block). +- **CI/CD and dev-tooling PRs** — changes confined to `.github/`, + `.ai-checks/`, or similar non-runtime infrastructure paths that add + no application behaviour. These are tooling/chore changes regardless + of their size. Established precedent: PRs #118, #122, #134. diff --git a/.ai-checks/pipeline-step-sync.md b/.ai-checks/pipeline-step-sync.md index e8f7b90..e830db7 100644 --- a/.ai-checks/pipeline-step-sync.md +++ b/.ai-checks/pipeline-step-sync.md @@ -81,3 +81,17 @@ must be reflected in the "Pipeline parallelism" paragraph of (e.g. renaming an internal helper, extracting a sub-function inside a step). - Pure bug fixes inside a step that don't change its contract. - Tests-only PRs. +- **Changes inside an existing step's implementation that do not alter the + step list.** If `PIPELINE_STEPS` in `episodes/models.py` is unchanged and + no `@DBOS.step()` decorators are added or removed in + `episodes/workflows.py`, then any change to the code *inside* a step + (new field extracted, LLM prompt adjusted, bug fixed) is not a pipeline + structural change. Do not require `README.md`'s high-level step-table to + update for per-field or per-behaviour changes within a step. +- **`doc/README.md` updates that describe per-step behaviour** (fields + extracted, edge-case handling, additive-only semantics for a field) are + compliant even if the `README.md` summary table is not updated — the table + documents step *names and roles*, not per-field implementation details. + A PR that updates `doc/README.md` to describe new behaviour inside an + existing step, while leaving `README.md`'s table unchanged, passes this + check.