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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
ci: add a fail-closed documentation-only fast path (#2534)
Call White9efb8b95c8e6
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.ymlindex bfa8ce576..8fab4697f 100644--- a/.github/workflows/lint.yml+++ b/.github/workflows/lint.yml@@ -14,7 +14,38 @@ env:FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: truejobs:+ 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.pyruff:+ needs: changes+ if: needs.changes.outputs.docs_only == 'false'runs-on: ubuntu-lateststeps:- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5@@ -59,6 +92,8 @@ jobs:pre-commit run --all-filesui-checks:+ needs: changes+ if: needs.changes.outputs.docs_only == 'false'runs-on: ubuntu-lateststeps:- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5@@ -79,6 +114,8 @@ jobs:npm testui-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-selectionshow-router-integration:+ needs: changes+ if: needs.changes.outputs.docs_only == 'false'runs-on: ubuntu-lateststeps:- 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/pythonbuild-linux-artifacts:+ needs: changes+ if: needs.changes.outputs.docs_only == 'false'runs-on: ubuntu-lateststeps:- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5@@ -212,6 +253,8 @@ jobs:retention-days: 1unit-test-shards:+ needs: changes+ if: needs.changes.outputs.docs_only == 'false'name: unit-tests (${{ matrix.shard }}/${{ matrix.shard-total }})runs-on: ubuntu-latesttimeout-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 checksenv:+ 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 ;;+ esacfor result in "$UNIT_RESULT" "$UI_RESULT" "$BROWSER_RESULT"; do- if [ "$result" != "success" ]; then+ if [ "$result" != "$expected" ]; thenecho "Unit/UI checks finished with result: $result"exit 1fidone- 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-lateststeps:- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5@@ -324,6 +380,8 @@ jobs:finpm-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 suitesenv:+ 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" ]; thenecho "Install/upgrade suites finished with result: $INSTALL_RESULT"exit 1fi- 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 runnerenv:+ 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" ]; thenecho "Windows installer smoke finished with result: $SMOKE_RESULT"exit 1fi- 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: 20strategy:fail-fast: falsediff --git a/docs/plans/ci-docs-fast-path.md b/docs/plans/ci-docs-fast-path.mdnew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.stdoutdiff --git a/tests/test_ci_pipeline.py b/tests/test_ci_pipeline.pyindex 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_commandsassert "npm ci" in build_commandsfor 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_otherassert '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, pytesassert (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.pyindex 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_staassert '--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.pynew file mode 100644index 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()