Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

ci: add a fail-closed documentation-only fast path (#2534)

Call White9efb8b95c8e6
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index bfa8ce576..8fab4697f 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -14,7 +14,38 @@ env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
jobs:
+ changes:
+ # Always report a workflow result; workflow-level paths-ignore would leave
+ # required contexts pending. Only proven narrative-only diffs skip work.
+ runs-on: ubuntu-latest
+ timeout-minutes: 3
+ permissions:
+ contents: read
+ outputs:
+ docs_only: ${{ steps.scope.outputs.docs_only }}
+ steps:
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+ with:
+ # Synthetic PR merge + both parents, without downloading all history.
+ fetch-depth: 2
+ - name: Classify the complete change
+ id: scope
+ run: python3 scripts/ci_docs_only.py
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+ if: steps.scope.outputs.docs_only == 'true'
+ with:
+ python-version: "3.12"
+ - name: Check repository guidance without application dependencies
+ if: steps.scope.outputs.docs_only == 'true'
+ env:
+ PYTEST_DISABLE_PLUGIN_AUTOLOAD: "1"
+ run: |
+ python -m pip install --disable-pip-version-check pytest==9.0.3
+ python -m pytest --noconftest -p no:cacheprovider -c /dev/null -q tests/test_repository_guidance.py
+
memory-insight-contract:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
# Repository branch protection still requires this historical context name.
# An administrator can rename that requirement after this compatibility job
# has landed; the job itself is a substantive removal contract, not a shim.
@@ -43,6 +74,8 @@ jobs:
tests/test_message_facts_generic.py
ruff:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -59,6 +92,8 @@ jobs:
pre-commit run --all-files
ui-checks:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -79,6 +114,8 @@ jobs:
npm test
ui-browser-checks:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
# Browser interactions do not depend on lint, Vitest, or the production
# bundle. Run alongside UI validation; the required unit-tests gate waits
# for both lanes, including failure/cancellation of either one.
@@ -110,6 +147,8 @@ jobs:
npm run test:chat-selection
show-router-integration:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -147,6 +186,8 @@ jobs:
run: node scripts/check_show_router.mjs --runtime-root .show-runtime-test --python .venv/bin/python
build-linux-artifacts:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -212,6 +253,8 @@ jobs:
retention-days: 1
unit-test-shards:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
name: unit-tests (${{ matrix.shard }}/${{ matrix.shard-total }})
runs-on: ubuntu-latest
timeout-minutes: 20
@@ -260,24 +303,37 @@ jobs:
runs-on: ubuntu-latest
# Keep UI validation in the existing required gate while allowing artifact
# consumers to start as soon as their production bundle is built.
- needs: [unit-test-shards, ui-checks, ui-browser-checks]
+ needs: [changes, unit-test-shards, ui-checks, ui-browser-checks]
if: always()
steps:
- name: Verify unit test shards and UI checks
env:
+ SCOPE_RESULT: ${{ needs.changes.result }}
+ DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
UNIT_RESULT: ${{ needs['unit-test-shards'].result }}
UI_RESULT: ${{ needs['ui-checks'].result }}
BROWSER_RESULT: ${{ needs['ui-browser-checks'].result }}
run: |
+ if [ "$SCOPE_RESULT" != "success" ]; then
+ echo "Change classification did not succeed."
+ exit 1
+ fi
+ case "$DOCS_ONLY" in
+ true) expected="skipped" ;;
+ false) expected="success" ;;
+ *) echo "Missing or invalid change classification."; exit 1 ;;
+ esac
for result in "$UNIT_RESULT" "$UI_RESULT" "$BROWSER_RESULT"; do
- if [ "$result" != "success" ]; then
+ if [ "$result" != "$expected" ]; then
echo "Unit/UI checks finished with result: $result"
exit 1
fi
done
- echo "All unit test shards and UI checks passed."
+ echo "Unit/UI results match the classified scope (docs_only=$DOCS_ONLY)."
migration-release-guard:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -324,6 +380,8 @@ jobs:
fi
npm-wrapper:
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false'
runs-on: [self-hosted, Linux, X64, avibe]
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
@@ -418,18 +476,29 @@ jobs:
install-upgrade-regression:
runs-on: ubuntu-latest
- needs: install-upgrade-shards
+ needs: [changes, install-upgrade-shards]
if: always()
steps:
- name: Verify all install and upgrade suites
env:
+ SCOPE_RESULT: ${{ needs.changes.result }}
+ DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
INSTALL_RESULT: ${{ needs['install-upgrade-shards'].result }}
run: |
- if [ "$INSTALL_RESULT" != "success" ]; then
+ if [ "$SCOPE_RESULT" != "success" ]; then
+ echo "Change classification did not succeed."
+ exit 1
+ fi
+ case "$DOCS_ONLY" in
+ true) expected="skipped" ;;
+ false) expected="success" ;;
+ *) echo "Missing or invalid change classification."; exit 1 ;;
+ esac
+ if [ "$INSTALL_RESULT" != "$expected" ]; then
echo "Install/upgrade suites finished with result: $INSTALL_RESULT"
exit 1
fi
- echo "All install and upgrade suites passed."
+ echo "Install/upgrade results match the classified scope (docs_only=$DOCS_ONLY)."
windows-install-smoke-runners:
name: windows-install-smoke (${{ matrix.runner }})
@@ -610,18 +679,29 @@ jobs:
windows-install-smoke:
runs-on: ubuntu-latest
- needs: windows-install-smoke-runners
+ needs: [changes, windows-install-smoke-runners]
if: always()
steps:
- name: Verify the installer on every PR-required runner
env:
+ SCOPE_RESULT: ${{ needs.changes.result }}
+ DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
SMOKE_RESULT: ${{ needs['windows-install-smoke-runners'].result }}
run: |
- if [ "$SMOKE_RESULT" != "success" ]; then
+ if [ "$SCOPE_RESULT" != "success" ]; then
+ echo "Change classification did not succeed."
+ exit 1
+ fi
+ case "$DOCS_ONLY" in
+ true) expected="skipped" ;;
+ false) expected="success" ;;
+ *) echo "Missing or invalid change classification."; exit 1 ;;
+ esac
+ if [ "$SMOKE_RESULT" != "$expected" ]; then
echo "Windows installer smoke finished with result: $SMOKE_RESULT"
exit 1
fi
- echo "The installer passed on every PR-required runner."
+ echo "Windows installer results match the classified scope (docs_only=$DOCS_ONLY)."
# The only job that starts the real service on Windows. A fresh install
# installs the Model Hub engine from the packaged manifest, saves API-key
@@ -782,7 +862,8 @@ jobs:
windows-agent:
name: windows-agent (${{ matrix.os }})
runs-on: ${{ matrix.os }}
- if: github.event_name != 'pull_request'
+ needs: changes
+ if: needs.changes.outputs.docs_only == 'false' && github.event_name != 'pull_request'
timeout-minutes: 20
strategy:
fail-fast: false
diff --git a/docs/plans/ci-docs-fast-path.md b/docs/plans/ci-docs-fast-path.md
new file mode 100644
index 000000000..a10e87768
--- /dev/null
+++ b/docs/plans/ci-docs-fast-path.md
@@ -0,0 +1,116 @@
+# Documentation-only CI fast path
+
+## Contract
+
+Owner request: avoid a full `lint` run for changes that are proven to affect
+only narrative documentation, reducing contention for the organization's
+20 hosted-runner slots. Base: `9b63a3009` (#2527). No branch-protection changes,
+production behavior, deployment, regression update, or merge authorization.
+
+- Always trigger the workflow; do not use workflow-level path filters, changed
+ file API pagination, or the push event's possibly truncated `commits` array.
+- A single lightweight `changes` job classifies the **complete Git tree diff**.
+ PR: compare the event base to the checked-out synthetic merge tree, verifying
+ its two parents match the event base/head. Push: compare `before` to `after`,
+ verifying the checked-out SHA and rejecting new/deleted/forced pushes.
+ Checkout depth two suffices for PR merge parents; fetch the validated prior
+ SHA on a multi-commit push only if missing. Unknown/missing/unreadable evidence
+ selects full CI; failure to execute classification leaves the final gates red.
+- Disable rename detection so both old and new paths count. Require ordinary
+ non-executable Git blobs (100644 / absent); symlinks, executable files,
+ submodules, type changes, malformed/empty diffs, mixed code/docs and unsupported
+ events select full CI. No user input can request a skip.
+- Initial allowlist: root AGENTS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md,
+ SECURITY.md, VISION.md, VISION_ZH.md; `.github/PULL_REQUEST_TEMPLATE.md`;
+ narrative `.md` files beneath `docs/`, **excluding the entire `docs/plans/`
+ subtree**, contract directories (`contracts` / `*-contracts`) and
+ docs/INSTALL_FOR_AI{,_ZH}.md. Tests dynamically scan all plans, not just a
+ finite list of known contract files. README.md
+ and README_ZH.md remain full (distribution metadata/install instructions).
+ Runtime Markdown in core/prompts, skills, UI fixtures and test assets is never
+ inferred to be documentation by extension alone. New executable docs must be
+ excluded when their consumer is introduced.
+- `changes` emits an explicit lowercase `docs_only=true|false` and a human
+ reason. A docs-only classification also runs the existing AGENTS/review-rule
+ contract in `tests/test_repository_guidance.py`, extracted unchanged from
+ the application-dependent Harness tests. A failed lightweight contract
+ fails `changes`; its output alone cannot authorize gate success.
+ All expensive root jobs require a successful classification with
+ `docs_only=false`. Artifact consumers remain dependent on the artifact job.
+- Preserve all nine required check names. The three existing aggregate jobs
+ remain `always()`, also require `changes`, and accept skipped producers **only**
+ for an explicit successful docs-only classification. Full-CI paths still
+ reject failure, cancellation, skip, or missing results. Leaf jobs skipped by
+ an intentional job-level condition are completed/skipped GitHub checks, not
+ absent/pending workflow checks. No fake check-runs or extra write permissions.
+- Documentation fast path uses four small hosted jobs (classifier + existing
+ three aggregate checks), no application dependency installs or test matrices.
+ Only Python and pinned pytest are prepared for the lightweight guidance
+ contract, with no app conftest/plugins or cache writes. It checks scope and
+ existing guidance requirements, not prose style. Code PR adds only the
+ classifier's small startup dependency, not full Git history downloads.
+
+## Validation plan
+
+Use existing pytest (no new test framework) with temporary real Git repositories
+and event fixtures: complete multi-commit diffs, changes beyond 300 files,
+renames across code/docs, non-ASCII names, mixed changes, merge parent/SHA
+mismatches, forced/new pushes, absent revisions and ambiguous events. Verify
+real workflow aggregate shell behavior for docs/full/error and each producer
+result, and changed job selection/required contexts. Keep existing CI boundary
+coverage rather than adding assertions of tool spelling.
+
+First PR run must use full CI because workflow/classifier/tests change. Exercise
+the classifier against a real historical docs-only PR's merge and event SHAs
+with the new script, and execute the actual aggregate shell steps locally for
+both paths. A real docs-only GitHub scheduling result remains a post-merge
+acceptance observation: do not add a bypass input, create a stacked PR or alter
+another Agent's PR just to manufacture it. No unrelated PRs are modified or
+cancelled. Exact-head Codex, all expected CI results and zero open review
+threads remain close-out gates.
+
+## Implementation and evidence
+
+- `scripts/ci_docs_only.py` is standard-library-only. Classification does not
+ install Avibe, execute documentation, read user data or call a changed-file
+ API. Errors choose full; missing/invalid outputs never authorize gate success.
+ Docs-only guidance validation installs pytest, not Avibe or its dependencies.
+- Workflow-level triggers and all nine required names are unchanged. Expected
+ docs result is: `changes` and three aggregate jobs succeed; expensive leaf
+ checks explicitly skip. These skipped leaf statuses are intentional completed
+ checks, not a claim that their underlying tests ran.
+- Initial focused tests: **89 passed**. After the review-boundary correction:
+ **94 passed** (classifier, pipeline and lightweight guidance); the remaining
+ Harness guidance tests pass separately (**9 passed**). Ruff/actionlint pass.
+ The 31 assertions moved to the lightweight owner are AST-identical to the
+ previous function. A real Git docs-only mutation that removes a required
+ AGENTS rule still classifies docs-only, but the actual standalone guidance
+ test fails; aggregate failure cases prove a failed `changes` cannot pass.
+- Real docs-only PR #2533 replayed read-only with a depth-two checkout:
+ base `9b63a3009bef1c81d95c6d866f909179fb7c9cc0`,
+ head `a66890ba25aa47b63314f1d2274fa6a605e17c80`,
+ synthetic merge `ea74a8cc110de06f0d1faef864ecda75463472fc`.
+ It changes only `AGENTS.md`; the new classifier emits `docs_only=true`.
+ No changes, comments, cancellations or pushes were made to that PR.
+- First full-CI run, exact-head Codex review, and a future real docs-only
+ scheduling observation remain separate verification layers. No time saving
+ is claimed measured until the corresponding GitHub run exists.
+
+## Review boundary correction
+
+Codex reviewed `6b664a178` and found one root-cause class: Markdown consumed by
+existing tests was incorrectly allowlisted. Independent read-only review
+identified the same cases. `test_model_hub_config.py` also reads implementation
+and routing plans; `test_show_page_legacy_ui_removed.py` globs all top-level
+plans; `test_harness_skill_guidance.py` reads root AGENTS.md. The fix is not a
+larger finite exception list: all plans remain full CI, and AGENTS retains its
+existing assertions in a dependency-light owner. No asserted contract was
+removed or weakened. This is the first findings-bearing reviewed head; no
+review-loop circuit breaker has fired. Full CI for that head passed in 11m16s,
+and its scope job explicitly reported full due to the workflow change.
+
+## Ownership
+
+Session sesp2bd67rp9c owns implementation, independent review decisions and the
+single delivery PR. A read-only design reviewer may challenge the skip boundary;
+no parallel mutable lane is needed for this tightly coupled workflow change.
diff --git a/scripts/ci_docs_only.py b/scripts/ci_docs_only.py
new file mode 100644
index 000000000..5fcf7ca6e
--- /dev/null
+++ b/scripts/ci_docs_only.py
@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Prove a complete event diff is narrative-only; uncertainty selects full CI.
+
+Only Git trees are consulted: no API file-list limits or truncated push commit
+arrays. See docs/plans/ci-docs-fast-path.md for the skip/required-check contract.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import subprocess
+
+ROOT_DOCS = frozenset({
+ "AGENTS.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "SECURITY.md",
+ "VISION.md", "VISION_ZH.md", ".github/PULL_REQUEST_TEMPLATE.md",
+})
+# Installed CLI documentation is executable contract input. All plans stay
+# full: tests also glob plan prose, so a list of individual exceptions cannot
+# safely describe that boundary. AGENTS.md has a dedicated lightweight check.
+CONTRACT_DOCS = frozenset({"docs/INSTALL_FOR_AI.md", "docs/INSTALL_FOR_AI_ZH.md"})
+
+
+def narrative_path(path: str) -> bool:
+ parts = path.split("/")
+ if any(part in ("", ".", "..") for part in parts) or "\\" in path:
+ return False
+ if path in ROOT_DOCS:
+ return True
+ return (
+ parts[0] == "docs" and PurePosixPath(path).suffix == ".md"
+ and not path.startswith("docs/plans/") and path not in CONTRACT_DOCS
+ and not any(part == "contracts" or part.endswith("-contracts") for part in parts[:-1])
+ )
+
+
+def git(repo: Path, *args: str) -> bytes:
+ return subprocess.run(
+ ["git", "-C", str(repo), *args], check=True, capture_output=True, timeout=60,
+ ).stdout
+
+
+def revision(value: object) -> str:
+ if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{40}", value) or value == "0" * 40:
+ raise ValueError("missing or invalid event revision")
+ return value
+
+
+def classify(event_name: str, event: dict, sha: str, repo: Path) -> tuple[bool, str]:
+ """Return explicit docs/full disposition; never infer docs from partial data."""
+ try:
+ if not isinstance(event, dict):
+ raise ValueError("event payload is not an object")
+ sha = revision(sha)
+ if git(repo, "rev-parse", "HEAD").decode().strip() != sha:
+ raise ValueError("checkout does not match event SHA")
+ if event_name == "pull_request":
+ pr = event["pull_request"]
+ base, head = revision(pr["base"]["sha"]), revision(pr["head"]["sha"])
+ header = git(repo, "cat-file", "commit", sha).split(b"\n\n", 1)[0]
+ parents = [line[7:].decode() for line in header.splitlines() if line.startswith(b"parent ")]
+ if parents != [base, head]:
+ raise ValueError("checkout is not the event's synthetic merge")
+ elif event_name == "push":
+ if any(event.get(flag) is not False for flag in ("created", "deleted", "forced")):
+ raise ValueError("new, deleted, forced or incomplete push event")
+ base = revision(event["before"])
+ if revision(event["after"]) != sha:
+ raise ValueError("push after does not match checkout")
+ try:
+ git(repo, "cat-file", "-e", f"{base}^{{commit}}")
+ except subprocess.CalledProcessError:
+ # A depth-two checkout may not contain before on a multi-commit
+ # push. Fetch that exact validated object, not an untrusted ref.
+ git(repo, "fetch", "--no-tags", "--depth=1", "origin", base)
+ else:
+ raise ValueError("unsupported event")
+
+ # No rename detection: code renamed to *.md must still include the
+ # deleted code path. NUL framing preserves spaces, tabs and Unicode.
+ raw = git(repo, "diff", "--raw", "-z", "--no-renames", "--no-abbrev",
+ "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", base, sha, "--")
+ if not raw or not raw.endswith(b"\0"):
+ raise ValueError("empty or incomplete diff")
+ fields = raw[:-1].split(b"\0")
+ if len(fields) % 2:
+ raise ValueError("incomplete diff records")
+ for header, name in zip(fields[::2], fields[1::2]):
+ meta = header.decode("ascii").split()
+ if len(meta) != 5 or not meta[0].startswith(":"):
+ raise ValueError("unexpected diff record")
+ old_mode, new_mode = meta[0][1:], meta[1]
+ if meta[4] not in {"A", "M", "D"} or {old_mode, new_mode} - {"000000", "100644"}:
+ return False, "non-document file type or mode changed"
+ path = name.decode("utf-8")
+ if not narrative_path(path):
+ return False, f"full CI required by {json.dumps(path, ensure_ascii=True)}"
+ return True, f"all {len(fields) // 2} changed paths are narrative documentation"
+ except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as exc:
+ # Do not print Git stderr, event payloads or arbitrary commit data.
+ return False, f"full CI: classification unavailable ({type(exc).__name__})"
+
+
+def main() -> None:
+ try:
+ event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text(encoding="utf-8"))
+ except (OSError, ValueError, KeyError):
+ event = {}
+ docs_only, reason = classify(
+ os.environ.get("GITHUB_EVENT_NAME", ""), event,
+ os.environ.get("GITHUB_SHA", ""), Path.cwd(),
+ )
+ # Output/write failures remain job failures; consumers require success AND
+ # a literal disposition, so no missing output can authorize a skip.
+ output = os.environ.get("GITHUB_OUTPUT")
+ if output:
+ with Path(output).open("a", encoding="utf-8") as stream:
+ stream.write(f"docs_only={str(docs_only).lower()}\n")
+ print(f"docs_only={str(docs_only).lower()}: {reason}")
+ summary = os.environ.get("GITHUB_STEP_SUMMARY")
+ if summary:
+ with Path(summary).open("a", encoding="utf-8") as stream:
+ stream.write(f"## CI scope: {'documentation only' if docs_only else 'full'}\n\n{reason}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_ci_docs_only.py b/tests/test_ci_docs_only.py
new file mode 100644
index 000000000..938375c73
--- /dev/null
+++ b/tests/test_ci_docs_only.py
@@ -0,0 +1,234 @@
+"""CI skip authority: real Git/event boundaries, never filename mocks.
+
+A false docs verdict hides runtime regressions. Existing pipeline tests cover
+job selection and real gate shell behavior; this file owns the Git evidence.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+import pytest
+
+from scripts.ci_docs_only import classify
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/ci_docs_only.py"
+
+
+def git(repo: Path, *args: str) -> str:
+ return subprocess.run(
+ ["git", "-C", str(repo), *args], check=True, capture_output=True, text=True,
+ ).stdout.strip()
+
+
+def write(repo: Path, path: str, text: str = "Narrative documentation\n") -> None:
+ target = repo / path
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(text, encoding="utf-8")
+
+
+def commit(repo: Path) -> str:
+ git(repo, "add", "-A")
+ git(repo, "-c", "user.name=CI Fixture", "-c", "[email protected]",
+ "commit", "-qm", "fixture")
+ return git(repo, "rev-parse", "HEAD")
+
+
+def repo(tmp_path: Path) -> Path:
+ root = tmp_path / "repo"
+ root.mkdir()
+ git(root, "init", "-q", "--initial-branch=main")
+ write(root, "AGENTS.md", "Initial guidance\n")
+ write(root, "core.py", "print('runtime')\n")
+ commit(root)
+ return root
+
+
+def push(repo: Path, base: str, **overrides) -> tuple[bool, str]:
+ after = git(repo, "rev-parse", "HEAD")
+ event = {"before": base, "after": after, "created": False, "deleted": False, "forced": False}
+ event.update(overrides)
+ return classify("push", event, after, repo)
+
+
[email protected](("path", "docs"), [
+ ("AGENTS.md", True),
+ ("CONTRIBUTING.md", True),
+ ("docs/普通 说明.md", True),
+ ("docs/guide\twith\nseparators.md", True),
+ (".github/PULL_REQUEST_TEMPLATE.md", True),
+ ("README.md", False),
+ ("README_ZH.md", False),
+ ("core/prompts/agent-instructions.md", False),
+ ("skills/use-avibe/SKILL.md", False),
+ ("docs/plans/ordinary-plan.md", False),
+ ("docs/plans/model-hub-implementation.md", False),
+ ("docs/plans/model-hub-routing-modes.md", False),
+ ("docs/plans/model-hub-contracts/api.md", False),
+ ("docs/plans/agent-core-contracts/context.md", False),
+ ("docs/plans/model-hub.md", False),
+ ("docs/plans/model-hub-shell-core-coverage.md", False),
+ ("docs/INSTALL_FOR_AI_ZH.md", False),
+ ("docs/fixture.json", False),
+ (".github/workflows/lint.yml", False),
+ ("scripts/ci_docs_only.py", False),
+ ("ui/package-lock.json", False),
+ ("tests/fixture.md", False),
+])
+def test_only_narrative_paths_can_skip(repo: Path, path: str, docs: bool) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ write(repo, path)
+ commit(repo)
+ assert push(repo, before)[0] is docs
+
+
+def test_complete_diff_not_last_commit_or_truncated_event(repo: Path) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ for i in range(305):
+ write(repo, f"docs/{i}.md")
+ write(repo, "zzz_runtime.py", "print('changed')\n")
+ commit(repo)
+ write(repo, "AGENTS.md")
+ commit(repo)
+ # Neither a 300-file list limit nor an event listing only the last doc
+ # commit may hide the earlier runtime change.
+ assert not push(repo, before, commits=[{"modified": ["AGENTS.md"]}])[0]
+
+
[email protected](("source", "target", "docs"), [
+ ("core.py", "docs/moved.md", False),
+ ("AGENTS.md", "runtime.py", False),
+ ("AGENTS.md", "docs/renamed.md", True),
+])
+def test_rename_checks_both_paths(repo: Path, source: str, target: str, docs: bool) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ (repo / target).parent.mkdir(parents=True, exist_ok=True)
+ git(repo, "mv", source, target)
+ commit(repo)
+ assert push(repo, before)[0] is docs
+
+
[email protected]("kind", ["executable", "symlink", "submodule", "type-change"])
+def test_doc_suffix_never_hides_non_document_modes(repo: Path, kind: str) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ if kind == "submodule":
+ git(repo, "update-index", "--add", "--cacheinfo", f"160000,{before},docs/module.md")
+ git(repo, "-c", "user.name=CI Fixture", "-c", "[email protected]", "commit", "-qm", "gitlink")
+ else:
+ path = repo / "AGENTS.md"
+ if kind == "executable":
+ path.chmod(0o755)
+ elif kind == "symlink":
+ (repo / "docs").mkdir()
+ (repo / "docs/link.md").symlink_to("../core.py")
+ else:
+ path.unlink()
+ path.symlink_to("core.py")
+ commit(repo)
+ assert not push(repo, before)[0]
+
+
+def synthetic_pr(repo: Path) -> tuple[dict, str]:
+ git(repo, "checkout", "-qb", "docs-change")
+ write(repo, "AGENTS.md")
+ head = commit(repo)
+ git(repo, "checkout", "-q", "main")
+ # Base advanced independently. Its code change is not this doc PR's change.
+ write(repo, "core.py", "print('new base')\n")
+ base = commit(repo)
+ git(repo, "-c", "user.name=CI Fixture", "-c", "[email protected]",
+ "merge", "--no-ff", "-qm", "PR merge", "docs-change")
+ return {"pull_request": {"base": {"sha": base}, "head": {"sha": head}}}, git(repo, "rev-parse", "HEAD")
+
+
+def test_pr_compares_actual_merge_tree_with_verified_parents_at_depth_two(repo: Path, tmp_path: Path) -> None:
+ event, sha = synthetic_pr(repo)
+ shallow = tmp_path / "shallow"
+ subprocess.run(["git", "clone", "-q", "--depth=2", repo.as_uri(), str(shallow)], check=True)
+ assert git(shallow, "rev-parse", "--is-shallow-repository") == "true"
+ assert classify("pull_request", event, sha, shallow)[0]
+ wrong = json.loads(json.dumps(event))
+ wrong["pull_request"]["head"]["sha"] = event["pull_request"]["base"]["sha"]
+ assert not classify("pull_request", wrong, sha, shallow)[0]
+ assert not classify("pull_request", event, event["pull_request"]["head"]["sha"], shallow)[0]
+
+
+def test_multi_commit_push_fetches_missing_before_not_all_history(repo: Path, tmp_path: Path) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ for i in range(3):
+ write(repo, f"docs/{i}.md")
+ commit(repo)
+ shallow = tmp_path / "push-checkout"
+ subprocess.run(["git", "clone", "-q", "--depth=2", repo.as_uri(), str(shallow)], check=True)
+ assert push(shallow, before)[0]
+
+
[email protected]("change", [
+ {"before": "0" * 40}, {"before": "f" * 40}, {"after": "f" * 40},
+ {"before": "--output=/tmp/wrong"}, {"created": True}, {"deleted": True},
+ {"forced": True}, {"forced": None},
+])
+def test_unknown_push_evidence_falls_back_to_full(repo: Path, change: dict) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ write(repo, "AGENTS.md")
+ commit(repo)
+ assert not push(repo, before, **change)[0]
+
+
+def test_empty_diff_and_unsupported_or_broken_events_are_not_docs(repo: Path) -> None:
+ sha = git(repo, "rev-parse", "HEAD")
+ assert not push(repo, sha)[0]
+ for name, payload in (("workflow_dispatch", {}), ("pull_request", {}), ("push", [])):
+ assert not classify(name, payload, sha, repo)[0]
+
+
+def test_cli_exports_explicit_disposition_and_missing_event_defaults_full(repo: Path, tmp_path: Path) -> None:
+ before = git(repo, "rev-parse", "HEAD")
+ write(repo, "AGENTS.md")
+ sha = commit(repo)
+ event = tmp_path / "event.json"
+ output = tmp_path / "output"
+ summary = tmp_path / "summary"
+ event.write_text(json.dumps({"before": before, "after": sha,
+ "created": False, "deleted": False, "forced": False}))
+ env = {**os.environ, "GITHUB_EVENT_NAME": "push", "GITHUB_SHA": sha,
+ "GITHUB_EVENT_PATH": str(event), "GITHUB_OUTPUT": str(output),
+ "GITHUB_STEP_SUMMARY": str(summary)}
+ result = subprocess.run([sys.executable, str(SCRIPT)], cwd=repo, env=env, capture_output=True, text=True)
+ assert result.returncode == 0, result.stderr
+ assert output.read_text() == "docs_only=true\n"
+ event.unlink()
+ result = subprocess.run([sys.executable, str(SCRIPT)], cwd=repo, env=env, capture_output=True, text=True)
+ assert result.returncode == 0, result.stderr
+ assert output.read_text().splitlines() == ["docs_only=true", "docs_only=false"]
+ assert "full" in summary.read_text()
+
+
+def test_guidance_remains_enforced_when_an_agents_only_diff_skips_application_tests(repo: Path) -> None:
+ root = SCRIPT.parents[1]
+ paths = (
+ "AGENTS.md", "tests/test_repository_guidance.py", ".agents/skills/pr-delivery-loop/SKILL.md",
+ "skills/background-watch-hook/scripts/wait_pr.py", "skills/background-watch-hook/scripts/wait_action.py",
+ )
+ for relative in paths:
+ target = repo / relative
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(root / relative, target)
+ before = commit(repo)
+ command = [sys.executable, "-m", "pytest", "--noconftest", "-p", "no:cacheprovider", "-c", "/dev/null", "-q",
+ "tests/test_repository_guidance.py"]
+ env = {**os.environ, "PYTEST_DISABLE_PLUGIN_AUTOLOAD": "1", "PYTHONDONTWRITEBYTECODE": "1"}
+ valid = subprocess.run(command, cwd=repo, env=env, capture_output=True, text=True)
+ assert valid.returncode == 0, valid.stdout + valid.stderr
+ agents = repo / "AGENTS.md"
+ agents.write_text(agents.read_text().replace("use the `background-watch-hook` skill", "use unmanaged polling"))
+ commit(repo)
+ assert push(repo, before)[0] # Scope remains docs; the independent check must reject its content.
+ invalid = subprocess.run(command, cwd=repo, env=env, capture_output=True, text=True)
+ assert invalid.returncode == 1, invalid.stdout + invalid.stderr
+ assert "test_pr_delivery_loop_delegates_waiters_to_background_watch_skill" in invalid.stdout
diff --git a/tests/test_ci_pipeline.py b/tests/test_ci_pipeline.py
index 98d40f99c..f62d139ba 100644
--- a/tests/test_ci_pipeline.py
+++ b/tests/test_ci_pipeline.py
@@ -349,13 +349,13 @@ def test_ui_checks_run_once_without_fencing_artifact_consumers() -> None:
jobs = _jobs()
checks = jobs["ui-checks"]
build = jobs["build-linux-artifacts"]
- assert not checks.get("needs")
- assert not build.get("needs")
+ assert checks.get("needs") == "changes"
+ assert build.get("needs") == "changes"
assert "ui-checks" in jobs["unit-tests"]["needs"]
assert "ui-browser-checks" in jobs["unit-tests"]["needs"]
assert "unit-test-shards" in jobs["unit-tests"]["needs"]
browsers = jobs["ui-browser-checks"]
- assert not browsers.get("needs")
+ assert browsers.get("needs") == "changes"
check_steps = [step for step in checks["steps"] if "run" in step]
build_steps = [step for step in build["steps"] if step.get("working-directory") == "ui"]
@@ -369,7 +369,7 @@ def test_ui_checks_run_once_without_fencing_artifact_consumers() -> None:
assert "npm ci" in check_commands
assert "npm ci" in build_commands
for job in (checks, browsers, build):
- assert not job.get("if")
+ assert job["if"] == "needs.changes.outputs.docs_only == 'false'"
assert not job.get("continue-on-error")
assert all(not step.get("if") and not step.get("continue-on-error") for step in job["steps"])
for name in ("install-upgrade-shards", "windows-install-smoke-runners"):
@@ -378,8 +378,11 @@ def test_ui_checks_run_once_without_fencing_artifact_consumers() -> None:
def test_windows_platform_checks_leave_only_latest_installer_smoke_on_prs() -> None:
jobs = _jobs()
- for name in ("windows-agent", "windows-model-hub", "windows-control-ipc"):
+ for name in ("windows-model-hub", "windows-control-ipc"):
assert jobs[name]["if"] == "github.event_name != 'pull_request'"
+ assert jobs["windows-agent"]["if"] == (
+ "needs.changes.outputs.docs_only == 'false' && github.event_name != 'pull_request'"
+ )
smoke = jobs["windows-install-smoke-runners"]
assert smoke["strategy"]["matrix"]["runner"] == (
@@ -387,7 +390,7 @@ def test_windows_platform_checks_leave_only_latest_installer_smoke_on_prs() -> N
)
smoke_steps = {step["name"]: step for step in smoke["steps"] if "name" in step}
assert "if" not in smoke_steps["Run Windows installer smoke test"]
- assert jobs["windows-install-smoke"]["needs"] == "windows-install-smoke-runners"
+ assert jobs["windows-install-smoke"]["needs"] == ["changes", "windows-install-smoke-runners"]
assert jobs["windows-install-smoke"]["if"] == "always()"
@@ -415,7 +418,7 @@ def test_install_suites_run_independently_without_losing_checks() -> None:
):
assert test_file in test_steps[0]["run"]
assert "docker info" in test_steps[0]["run"]
- assert jobs["install-upgrade-regression"]["needs"] == "install-upgrade-shards"
+ assert jobs["install-upgrade-regression"]["needs"] == ["changes", "install-upgrade-shards"]
def test_distribution_contracts_consume_same_run_artifacts_without_fencing_other_installers() -> None:
@@ -457,11 +460,11 @@ def test_distribution_contracts_consume_same_run_artifacts_without_fencing_other
assert 'AVIBE_CORE_SDIST="$(ls dist/avibe_os-*.tar.gz)"' in contracts["run"]
assert "pytest tests/test_distribution_artifacts.py -v -ra" in contracts["run"]
assert not contracts.get("continue-on-error")
- assert jobs["install-upgrade-regression"]["needs"] == "install-upgrade-shards"
+ assert jobs["install-upgrade-regression"]["needs"] == ["changes", "install-upgrade-shards"]
assert jobs["windows-install-smoke-runners"]["needs"] == "build-linux-artifacts"
# Branch protection requires `windows-install-smoke`; the per-runner matrix
# reports under other names, so the required name gates on all of them.
- assert jobs["windows-install-smoke"]["needs"] == "windows-install-smoke-runners"
+ assert jobs["windows-install-smoke"]["needs"] == ["changes", "windows-install-smoke-runners"]
assert jobs["windows-install-smoke"]["if"] == "always()"
@@ -487,41 +490,72 @@ def test_distribution_contract_command_fails_on_errors_and_skips(tmp_path, pytes
assert (result.returncode == 0) == (pytest_exit == 0 and "skipped" not in summary), result.stdout + result.stderr
[email protected]("result", ["success", "failure", "cancelled", "skipped", ""])
-def test_install_gate_fails_unless_all_suites_succeeded(tmp_path: Path, result: str) -> None:
- gate = _jobs()["install-upgrade-regression"]
[email protected]("gate_name", ["unit-tests", "install-upgrade-regression", "windows-install-smoke"])
+def test_required_gates_accept_skips_only_for_proven_docs_and_fail_closed(tmp_path: Path, gate_name: str) -> None:
+ gate = _jobs()[gate_name]
assert gate["if"] == "always()"
+ assert "changes" in gate["needs"]
step, = gate["steps"]
- assert step["env"] == {"INSTALL_RESULT": "${{ needs['install-upgrade-shards'].result }}"}
- command = subprocess.run(
- ["bash", "-e", "-c", step["run"]], cwd=tmp_path,
- env={**os.environ, "INSTALL_RESULT": result}, capture_output=True, text=True,
- )
- assert (command.returncode == 0) == (result == "success"), command.stdout
-
-
-def test_existing_required_gate_fails_unless_every_dependency_succeeded(tmp_path: Path) -> None:
- gate = _jobs()["unit-tests"]
- assert gate["if"] == "always()"
- step, = gate["steps"]
- assert step["env"] == {
- "UNIT_RESULT": "${{ needs['unit-test-shards'].result }}",
- "UI_RESULT": "${{ needs['ui-checks'].result }}",
- "BROWSER_RESULT": "${{ needs['ui-browser-checks'].result }}",
- }
- # The gate checks each dependency independently; a Cartesian product adds
- # no failure class. Prove all-success and each dependency failing in turn.
- cases = [dict.fromkeys(step["env"], "success")]
- for name in step["env"]:
- for outcome in ("failure", "cancelled", "skipped", ""):
- cases.append({**cases[0], name: outcome})
- for results in cases:
+ assert step["env"]["SCOPE_RESULT"] == "${{ needs.changes.result }}"
+ assert step["env"]["DOCS_ONLY"] == "${{ needs.changes.outputs.docs_only }}"
+ producer_env = {name: value for name, value in step["env"].items()
+ if name not in {"SCOPE_RESULT", "DOCS_ONLY"}}
+ producers = set(gate["needs"]) - {"changes"}
+ assert set(producer_env.values()) == {f"${{{{ needs['{name}'].result }}}}" for name in producers}
+
+ cases = []
+ for docs_only, expected in (("false", "success"), ("true", "skipped")):
+ good = {"SCOPE_RESULT": "success", "DOCS_ONLY": docs_only,
+ **dict.fromkeys(producer_env, expected)}
+ cases.append((good, True))
+ # Each producer must match the classified scope, independently.
+ for name in producer_env:
+ for outcome in ("success", "failure", "cancelled", "skipped", ""):
+ if outcome != expected:
+ cases.append(({**good, name: outcome}, False))
+ for scope_result in ("failure", "cancelled", "skipped", ""):
+ cases.append(({**good, "SCOPE_RESULT": scope_result}, False))
+ for invalid in ("", "TRUE", "unknown"):
+ cases.append(({**good, "DOCS_ONLY": invalid}, False))
+ for results, passes in cases:
result = subprocess.run(
- ["bash", "-e", "-c", step["run"]],
- cwd=tmp_path,
- env={**os.environ, **results},
- capture_output=True,
- text=True,
- check=False,
+ ["bash", "-e", "-c", step["run"]], cwd=tmp_path,
+ env={**os.environ, **results}, capture_output=True, text=True, check=False,
)
- assert (result.returncode == 0) == all(value == "success" for value in results.values()), result.stdout
+ assert (result.returncode == 0) == passes, (results, result.stdout, result.stderr)
+
+
+def test_docs_scope_gates_all_work_without_filtering_away_required_checks() -> None:
+ workflow = yaml.safe_load((ROOT / ".github/workflows/lint.yml").read_text())
+ events = workflow[True] # PyYAML YAML 1.1 reads the Actions `on` key as True.
+ assert events["pull_request"] is None
+ assert not any(key.startswith("paths") for key in events["push"])
+ jobs = workflow["jobs"]
+ required = {"ruff", "unit-tests", "show-router-integration", "memory-insight-contract",
+ "migration-release-guard", "npm-wrapper", "build-linux-artifacts",
+ "install-upgrade-regression", "windows-install-smoke"}
+ assert required <= jobs.keys()
+ gates = {"unit-tests", "install-upgrade-regression", "windows-install-smoke"}
+ for name, job in jobs.items():
+ if name == "changes" or name in gates:
+ continue
+ # Every expensive root depends on scope; artifact consumers may depend
+ # on the gated producer. No new job can silently evade docs selection.
+ needs = job.get("needs", [])
+ needs = [needs] if isinstance(needs, str) else needs
+ if "changes" in needs:
+ assert "needs.changes.outputs.docs_only == 'false'" in job["if"]
+ else:
+ assert needs == ["build-linux-artifacts"], name
+ assert "always()" not in job.get("if", "")
+ assert not job.get("continue-on-error")
+ scope = jobs["changes"]
+ assert scope["outputs"]["docs_only"] == "${{ steps.scope.outputs.docs_only }}"
+ assert not scope.get("if") and not scope.get("continue-on-error")
+ command, = [s for s in scope["steps"] if s.get("id") == "scope"]
+ assert command["run"] == "python3 scripts/ci_docs_only.py"
+ assert not command.get("continue-on-error")
+ guidance, = [s for s in scope["steps"] if "test_repository_guidance.py" in s.get("run", "")]
+ assert guidance["if"] == "steps.scope.outputs.docs_only == 'true'"
+ assert not guidance.get("continue-on-error")
+ assert "--noconftest" in guidance["run"]
diff --git a/tests/test_harness_skill_guidance.py b/tests/test_harness_skill_guidance.py
index 2f112fb30..aa8c2d47e 100644
--- a/tests/test_harness_skill_guidance.py
+++ b/tests/test_harness_skill_guidance.py
@@ -233,51 +233,6 @@ def test_background_watch_skill_uses_bundled_waiters_and_persists_managed_pr_sta
assert '--workflow lint' in body
-def test_pr_delivery_loop_delegates_waiters_to_background_watch_skill() -> None:
- body = _read(".agents/skills/pr-delivery-loop/SKILL.md")
- flat = " ".join(body.split())
- agents = _read("AGENTS.md")
-
- assert "`background-watch-hook` owns managed waits, waiter scripts, cursor mechanics" in flat
- assert "Load that skill before a managed wait." in flat
- assert "do not vendor or reimplement it in a repository" in flat
- assert ".agents/skills/pr-delivery-loop/scripts/" not in body
- assert not (ROOT / ".agents/skills/pr-delivery-loop/scripts").exists()
- assert not (ROOT / ".agents/skills/pr-delivery-loop/tests").exists()
-
- assert "the `pr-delivery-loop` skill for every implementation task" in agents
- assert "use the `background-watch-hook` skill" in agents
- assert "one durable `--forever` combined PR/CI Watch" in agents
- assert "one durable combined PR + CI Watch per owner/concern" in flat
- assert "`wait_pr.py`, `--forever`, required `--workflow` names" in flat
- assert "no fixed `--sha` during a normal delivery loop" in flat
- assert "Set `--timeout 0` on both supervisor and waiter; do not impose a lifetime cap." in flat
- assert "disable the Watch's per-cycle timeout" in agents
- assert "Never reseed, rotate, or replace the cursor between rounds." in flat
- assert "never use `--forever`" not in body
- # Gate on captured head-bound evidence, not the reaction's persistent level.
- assert "A Codex `+1` **on the PR body** is a pass only when the original durable Watch" in flat
- assert "captured it as new after the current head epoch began" in flat
- assert "the prior-head review was already terminal, and the head is unchanged" in flat
- assert "If the timeline cannot bind it, trigger review on the unchanged head" in flat
- assert "require a SHA-bearing verdict" in flat
- assert "`Codex Review: Didn't find any major issues` and name the current reviewed SHA" in flat
- assert "`Reviewed commit` alone is not a pass; findings reviews use it too." in flat
- # The bot quotes `@codex review` in its own boilerplate, so a body-text search
- # for the trigger matches the verdicts it is supposed to be distinguished from.
- assert "Save the trigger comment ID returned by your own write and read it back." in flat
- assert "Never select the last comment or search bodies for the trigger text." in flat
- # Only the *passing* auto-review is reaction-only. Broadening that to every
- # auto-review tells an agent to ignore a findings review and keep waiting on
- # a reaction that will never describe it.
- assert "Act on auto-review findings as inline reviews." in flat
- assert "A clean auto-review may pass only through the PR-body reaction" in flat
- assert "trigger review when a SHA-bearing pass comment is needed" in flat
- assert "rather than waiting for one to appear automatically" in flat
- assert (ROOT / "skills/background-watch-hook/scripts/wait_pr.py").is_file()
- assert (ROOT / "skills/background-watch-hook/scripts/wait_action.py").is_file()
-
-
def test_pr_delivery_loop_keeps_one_optional_reference_out_of_routine_loading() -> None:
directory = ROOT / ".agents/skills/pr-delivery-loop"
body = (directory / "SKILL.md").read_text()
diff --git a/tests/test_repository_guidance.py b/tests/test_repository_guidance.py
new file mode 100644
index 000000000..d46a88de8
--- /dev/null
+++ b/tests/test_repository_guidance.py
@@ -0,0 +1,55 @@
+"""Repository guidance contracts that can run without application dependencies.
+
+The docs-only lane executes this module with pytest --noconftest, so changing
+AGENTS.md cannot bypass its existing guidance checks. Keep runtime/CLI examples
+in test_harness_skill_guidance.py, whose input files always select full CI.
+"""
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_pr_delivery_loop_delegates_waiters_to_background_watch_skill() -> None:
+ body = (ROOT / ".agents/skills/pr-delivery-loop/SKILL.md").read_text()
+ flat = " ".join(body.split())
+ agents = (ROOT / "AGENTS.md").read_text()
+
+ assert "`background-watch-hook` owns managed waits, waiter scripts, cursor mechanics" in flat
+ assert "Load that skill before a managed wait." in flat
+ assert "do not vendor or reimplement it in a repository" in flat
+ assert ".agents/skills/pr-delivery-loop/scripts/" not in body
+ assert not (ROOT / ".agents/skills/pr-delivery-loop/scripts").exists()
+ assert not (ROOT / ".agents/skills/pr-delivery-loop/tests").exists()
+
+ assert "the `pr-delivery-loop` skill for every implementation task" in agents
+ assert "use the `background-watch-hook` skill" in agents
+ assert "one durable `--forever` combined PR/CI Watch" in agents
+ assert "one durable combined PR + CI Watch per owner/concern" in flat
+ assert "`wait_pr.py`, `--forever`, required `--workflow` names" in flat
+ assert "no fixed `--sha` during a normal delivery loop" in flat
+ assert "Set `--timeout 0` on both supervisor and waiter; do not impose a lifetime cap." in flat
+ assert "disable the Watch's per-cycle timeout" in agents
+ assert "Never reseed, rotate, or replace the cursor between rounds." in flat
+ assert "never use `--forever`" not in body
+ # Gate on captured head-bound evidence, not the reaction's persistent level.
+ assert "A Codex `+1` **on the PR body** is a pass only when the original durable Watch" in flat
+ assert "captured it as new after the current head epoch began" in flat
+ assert "the prior-head review was already terminal, and the head is unchanged" in flat
+ assert "If the timeline cannot bind it, trigger review on the unchanged head" in flat
+ assert "require a SHA-bearing verdict" in flat
+ assert "`Codex Review: Didn't find any major issues` and name the current reviewed SHA" in flat
+ assert "`Reviewed commit` alone is not a pass; findings reviews use it too." in flat
+ # The bot quotes `@codex review` in its own boilerplate, so a body-text search
+ # for the trigger matches the verdicts it is supposed to be distinguished from.
+ assert "Save the trigger comment ID returned by your own write and read it back." in flat
+ assert "Never select the last comment or search bodies for the trigger text." in flat
+ # Only the *passing* auto-review is reaction-only. Broadening that to every
+ # auto-review tells an agent to ignore a findings review and keep waiting on
+ # a reaction that will never describe it.
+ assert "Act on auto-review findings as inline reviews." in flat
+ assert "A clean auto-review may pass only through the PR-body reaction" in flat
+ assert "trigger review when a SHA-bearing pass comment is needed" in flat
+ assert "rather than waiting for one to appear automatically" in flat
+ assert (ROOT / "skills/background-watch-hook/scripts/wait_pr.py").is_file()
+ assert (ROOT / "skills/background-watch-hook/scripts/wait_action.py").is_file()