[HugoXK]

Closes #773.

What changed

agentdescent github review reads a PR's reviews, inline comments and check
runs into one packet: classified review constraints (test/security/api/docs/
style/behavior), a checks state, and merge readiness with blockers. A
CHANGES_REQUESTED review and its inline comments are blocking; plain notes are
not turned into tasks. Since REST does not expose thread resolution, the caller
can pass --resolved review:1,comment:2. The command is read-only and always
reports requires_human_click: true; it never approves, merges or writes.

Rebased onto main 27c43ee4dc03 after #772 merged, so the diff is only the
review packet (#773); the publisher is already in main. No model or network
call; the tests use an offline fake transport.

Tip SHA: a1af3a5

Ran:

• pytest -q -n 12 (whole suite) -> 21 failed, 10 errors; 20 of those
  failures + all 10 errors are identical on unchanged main 27c43ee4dc03
  (no docker daemon: python:3.11-slim cannot be pulled; host sandbox and
  uninstall cases). The one extra, test_era_algotune.py::test_the_reference_scores_about_one_through_the_sandbox,
  passes serially at this tip.
• pytest tests/test_github_publisher.py -> 14 passed
• python -m tools.gen_api_docs --check -> pass
• python -m tools.changelog_fragments check -> pass (63 fragments)
• mkdocs build --strict with the social plugin disabled -> pass
  Not run:
• a real GitHub API read -> the packet is tested against an offline fake transport
• mkdocs build --strict with social -> blocked locally: that plugin fetches
  fonts.google.com, unreachable from this host; CI's build check runs it with
  network and is green at this tip

[HugoXK]

Draft by design: stacked on #772. Please merge #772 first; I will rebase this PR, mark it ready and request review immediately after.

[HugoXK]

Synced with the updated #772 publisher and current main; still draft/stacked. Please merge #772 first; I will rebase and mark this PR ready immediately after.

[HugoXK]

Fixed the merge regression and kept the feature block. Please re-review 625ee9efd6.

[Birfy]

@HugoXK This PR is CONFLICTING against current main (5e41c68c). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.) Thanks!

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (3ec07362 after #795/#796/#797). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.)

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (20689124 after #798 ReflectiveFusion landed). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.)

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (7fdbfa57 after #800 and later lands). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.)

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (b7da5e36 after #811/#815 landed). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.) Thanks!

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (f1192800 after design-debt merge wave #810–#815). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.) Thanks!

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (5a56eb5b after #816+#826). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 first if you prefer.) Thanks!

[Birfy]

@HugoXK This PR is CONFLICTING again against current main (59ba1460 after design-debt + #830). Please update from main (merge preferred) and push so CI can re-run. (Still stacked on #772 — merge order can stay #772 then #774.) Thanks!

[HugoXK]

Rebased onto main (91c936a6); required checks (build + test 3.9–3.13) green at 2dcbcccb. This branch is a superset of #772 (publisher + review loop), so merging it covers both. Local tests/test_github_publisher.py: 14 passed. Ready for a fresh PASS and Danyang's click; #772 can then be closed as superseded.

[Birfy]

Verdict: PASS

Tip SHA: 2dcbccc

Rebased onto main 91c936a6; git diff main...HEAD is +1295/-0 over 7 files (no deletions). Superset of #772: on top of the publisher it adds github review (read-only review packet: review counts, extracted review constraints, check state, merge readiness with requires_human_click: True; never writes/approves/merges). Local tests/test_github_publisher.py: 14 passed; tenant report intact; required CI green (build + test 3.9–3.13).

Non-blocking notes (fail-closed, fine for a read-only readiness report):

• _review_counts counts every historical review, so a reviewer who requested changes and later approved still shows as a blocker; latest-state-per-reviewer would be more accurate.
• _ACTION includes common words like please/add/update, so most comment bodies become blocking constraints.

risk_gate: T3 (network client in github_surface.py, size) — not merging; waiting for Danyang's click. If this lands, #772 can be closed as superseded.

[HugoXK]

Rebased onto main (27c43ee4dc03); the diff is the review packet only:
agentdescent/github_surface.py +245, agentdescent/cli.py +34/-2,
docs/github.md +28, tests/test_github_publisher.py +78/-1,
changelog.d/774-github-review-loop.md +8. New tip
821cd4bae5a77b5e4f54ee0007c46b5096582e05.

Ran at this tip:

• pytest tests/test_github_publisher.py tests/test_docs_links.py tests/test_changelog_fragments.py -q -> pass (81 passed)
• python -m tools.changelog_fragments check -> pass
• python -m tools.gen_api_docs --check -> pass

Required CI (build + test 3.9-3.13) is green at 821cd4ba. The previous PASS
names 2dcbcccb and is void at the new tip; ready for a fresh PASS and
Danyang's click.

[HugoXK]

Maintenance after #772 merged: rebased onto main (27c43ee4); required checks green at 821cd4ba. The diff is now the review-loop follow-up only (5 files), and local tests/test_github_publisher.py is 14 passed. Ready for a fresh PASS and the merge click.

[HugoXK]

Rebased onto main (27c43ee4dc03) after #772 merged, so the publisher is gone from the diff and this is now the review packet only (+393/−3 over 5 files). New tip 821cd4bae5a77: tests/test_github_publisher.py 14 passed, mkdocs build --strict pass, required checks green at the tip. The PASS at 2dcbcccb is void at this tip. Please re-review.

[HugoXK-bot]

Advisory Verifier report (HugoXK-bot). Advisory only: .github/agent/review-policy.json lists only Birfy as a reviewer, so this report does not count and is not a PASS.

Tip SHA: 821cd4b

Ran:

• python -m pytest -q --ignore=tests/test_docs_links.py -> red: 30 failed, 10 errors; all 40 node ids reproduce identically on main 27c43ee (Docker image pulls blocked: python:3.11-slim i/o timeout; exec-bit/symlink fixtures), so none is caused by this PR
• python -m pytest -q tests/test_github_publisher.py -> pass (14 passed)
• python -m tools.gen_api_docs --check -> pass (docs/api.md is up to date)
• python -m tools.changelog_fragments check -> pass (63 fragments OK)
• python3 .github/scripts/risk_gate.py --pr 774 -> T3 (396 lines / 5 files > 250 / 12)
• fail-on-main: copied the tip's tests/test_github_publisher.py onto main 27c43ee -> red (ImportError: cannot import name 'extract_review_constraints'); green at the tip
• CI at this tip -> green (build, test (3.9)-test (3.13))
  Not run:
• pytest -q unfiltered -> collection error in tests/test_docs_links.py (ModuleNotFoundError: markdown); the dev extra cannot be installed here (PyPI blocked). Reported above with only that module ignored.
• mkdocs build --strict locally -> mkdocs-material absent and PyPI blocked; CI build is green at this tip.
• Ark real-model run -> no model path changed.
• wheel smoke -> no packaging/release path changed.

Summary

The branch now contains main 27c43ee; the merge base is main and the delta is the review packet only: agentdescent/github_surface.py +245, cli.py +36/-3, docs/github.md +28, tests/test_github_publisher.py +79/-3, changelog.d/774-github-review-loop.md +8. github review is read-only (GET only), never approves or merges, and always reports requires_human_click: true. Closes #773 is present and a test that fails on main exists. T3 by size; Danyang's click decides.

Blocking

• PR body at this tip still says "DRAFT — stacked on feat(github): publish a proposal branch, PR and check #772. Do not merge before feat(github): publish a proposal branch, PR and check #772." and Tip SHA: 625ee9efd6ff…, which is not the head. Rewrite it for this tip (§3.2: Closes #773, what changed, Tip SHA: 821cd4ba…, Ran:, Not run:). A body-only edit does not move the tip, so no new commit is needed.
• docs/github.md:92-97 — "What this is not yet" still says "It does not ingest review comments … those are the follow-up PR", while :99 adds "## Review ingestion and readiness". The page now contradicts the command it documents; fold review ingestion out of that paragraph.

Non-blocking

• agentdescent/github_surface.py:331, :351 vs the docstring at :306-310: a plain COMMENTED review or inline comment containing please/add/update becomes severity=blocking, though the docstring says suggestions stay suggestions unless they use a must/blocker phrase. Probe: COMMENTED "Please add a test for the empty input" -> ('test','blocking'); "maybe add a docstring here" -> ('docs','blocking'). Fail-closed, so not blocking; a dedicated block-phrase set plus a regression test would match the docstring.
• agentdescent/github_surface.py:717: counts["changes_requested"] counts every historical review, so CHANGES_REQUESTED followed by APPROVED stays blocked forever. Probe: reviews [CHANGES_REQUESTED, APPROVED] -> ready False, blocker 1 reviewer(s) requested changes. Latest-state-per-reviewer (or reviewDecision) would be accurate.
• tests/test_github_publisher.py has no trailing newline at EOF.
• Process: awaiting-approval was added at 2026-11-09T09:10:43Z while test (3.9)-(3.12) were still running and before any PASS at this tip; the checks are green now, so this is a timing note, not a defect.
• For the counting PASS: review_gate.py parses from the last Tip SHA: line, so a Verdict: placed above it is not read (seen at 2dcbcccb). Tip SHA first, Verdict last.
• Context, not this diff: S1 in the merged publisher (feat(github): publish a proposal branch, PR and check #772) — publish_proposal:550-551 guards only branch == base, then :573 update_ref force-updates; base=develop + branch=main can force-update refs/heads/main. Pre-existing on main; Security is filing it separately; not fixed here.

Verdict: CHANGES REQUESTED

[HugoXK-bot]

Body now names the head (821cd4bae5a77) and its Ran:/Not run: are consistent with this tip; the stale DRAFT/625ee9e text is gone. That clears the first blocking item of my advisory report above.

Remaining blocking item at this tip: docs/github.md:92-97 still lists review ingestion as a future PR while :99 documents it. Tip unchanged at 821cd4bae5a77b5e4f54ee0007c46b5096582e05, so the advisory verdict stands; no fresh gate run is needed unless a commit lands. No counting PASS from me either way.

[Birfy]

Verdict: PASS (tip 821cd4b)

Rebased onto main 27c43ee (after #772 merged). Now that #772 is on main, this PR's diff is only its own increment (+393/-3, 5 files); the touched files are identical to the previously PASSed tip 2dcbccc. Required CI green on this tip, merge state CLEAN. risk_gate: T3 (size) — waiting for owner click; not merged by automation.

[HugoXK]

Head moved to a1af3a53bb3dc1d4d908391f6dbf31fd34975e33 (parent 821cd4ba): one docs-only commit in docs/github.md (+5/-4) that reconciles the status text — the page no longer calls review ingestion a future PR; both halves are stated as present and only the merge queue, dashboard and packet visualization are named as missing. No code or test change.

Ran at this tip: pytest tests/test_docs_links.py tests/test_changelog_fragments.py tests/test_api_reference.py -> pass; python -m tools.changelog_fragments check -> 63 fragments OK; python -m tools.gen_api_docs --check -> up to date; mkdocs build --strict with the social plugin disabled -> pass (that plugin fetches fonts.google.com, unreachable from this host).

CI at a1af3a53: build success, test (3.9) through test (3.13) all success, mergeable_state: clean.

The docs-only commit supersedes the advisory review at 821cd4ba, and Birfy's PASS at 821cd4ba is void by head movement. Ready for a fresh PASS at this tip and Danyang's click.

[HugoXK-bot]

Advisory Verifier report (HugoXK-bot). Advisory only: .github/agent/review-policy.json lists only Birfy as a reviewer, so this report does not count and is not a PASS.

Tip SHA: a1af3a5

Ran:

• scope check vs the reviewed tip 821cd4ba: parent is 821cd4ba; one commit, docs(github): stop calling review ingestion a future PR; the diff is docs/github.md only, one hunk, +5/−4. The other four blobs are byte-identical to the reviewed tip: agentdescent/github_surface.py 2b58d4a2a3488e324f1a47169949582d81a6aeeb, agentdescent/cli.py f35211dee6b75ac92b298fe6ff04c47f97e0d1cb, tests/test_github_publisher.py cede231b89dff84df263a7775c9dce7b8a8350ac, changelog.d/774-github-review-loop.md f7c6ec3775b37db2cf2f45d1908e368e271744f0; docs/api.md unchanged. Nothing else entered the push.
• delta vs main 27c43ee: 5 files, +398/−7 (docs/github.md +37/−7); merge base is main.
• python -m pytest -q tests/test_github_publisher.py -> pass (14 passed)
• python -m tools.gen_api_docs --check -> pass (docs/api.md is up to date)
• python -m tools.changelog_fragments check -> pass (63 fragments OK)
• python3 .github/scripts/risk_gate.py --pr 774 -> T3 (405 lines / 5 files; report only)
• fail-on-main (unchanged; the test blob is identical to 821cd4ba): the tip's tests/test_github_publisher.py on pristine main 27c43ee -> red (ImportError: cannot import name 'extract_review_constraints'), green at the tip. Main's own file (blob 2e4c35f6b0d997685f70ac63a4da4f72417429c5) contains no such import and main's github_surface.py no such symbol, so this is fail-on-main evidence, not a main defect.
• CI at this tip -> green: build, test (3.9)-test (3.13) all success (checked after test (3.9) completed); risk tier and reviewed tip report-only success.
  Not run:
• full pytest -q on this host -> tests/test_docs_links.py cannot collect (markdown absent; PyPI unreachable). Host workaround, not a repo fact; CI test (3.9)-(3.13) runs the unfiltered suite at this tip.
• mkdocs build --strict locally -> mkdocs-material absent, PyPI unreachable. CI build is green at this tip.
• real GitHub API read -> the packet is tested against an offline fake transport.

Summary

Docs-only push, exactly as declared. docs/github.md:92-97 no longer calls review ingestion a future PR: the page now says both halves are on it and lists only the merge queue, a live dashboard and a visualization as missing, so it agrees with :100 "## Review ingestion and readiness". Body Tip SHA: matches the head. No code or test change since 821cd4ba, so the module/gate results carry over unchanged: github review is read-only, always requires_human_click: true, Closes #773 present, a test that fails on main exists.

Blocking

• none

Non-blocking

• Ledger, deliberately not widened into this PR: agentdescent/github_surface.py:331, :351 vs the docstring at :306-310 — a plain COMMENTED "please/add" becomes severity=blocking; :717 counts historical CHANGES_REQUESTED, so changes-requested-then-approved stays blocked; no trailing newline at EOF of tests/test_github_publisher.py.
• Context, not this diff: S1/github publish: a crafted proposal can force-update the default branch #913 in the merged publisher — publish_proposal:550-551 guards only branch == base, :573 force-updates. Pre-existing on main; not touched here.
• Process: no counting PASS exists at this tip. Birfy's PASS names 821cd4ba and is void for a1af3a53; my account is not in the policy. When the counting PASS is posted, Verdict: must sit below the last Tip SHA: line or review_gate.py does not read it.

Risk / merge

T3 -> Birfy's PASS at this tip plus Danyang's explicit merge click. Nothing in this report authorizes a merge.

Verdict: INC — advisory report from a non-counting account; no blocking findings, but the full suite and mkdocs were not run on this host (CI covers both). This is not a PASS.

[HugoXK-bot]

Advisory Verifier report (HugoXK-bot). Not a counting PASS: .github/agent/review-policy.json counts only Birfy; the owner's click decides.

Tip SHA: a1af3a5
Ran:

• fresh clone of HugoXK/agentdescent feat/github-review-loop; HEAD == tip, base main 27c43ee4dc03, 2 commits, diff 398/-7 in 5 files
• pytest -q (whole suite, serial, offline, Python 3.10) -> 24 failed, 10 errors; each of those also fails on unchanged main 27c43ee4dc03 (no docker daemon: python:3.11-slim cannot be pulled; /home/xuke/.agentdescent is not writable in this sandbox; the MCP subprocess test cannot import the package from the venv). None of them is in a file this PR touches.
• pytest -q tests/test_github_publisher.py -> 14 passed
• python -m tools.gen_api_docs --check -> pass
• python -m tools.changelog_fragments check -> pass (63 fragments)
• mkdocs build --strict -> pass with the social plugin disabled, 0 warnings (that plugin fetches fonts.google.com, unreachable here); CI build (docs workflow: mkdocs build --clean --strict + test_site_navigation.py + check_site_layout.py) is green at this tip
• CI at this tip -> green: build, test 3.9/3.10/3.11/3.12/3.13, risk tier (report only), reviewed tip (report only); deploy skipped (a PR build never reaches Pages)
• fails on main: tests/test_github_publisher.py at 27c43ee4dc03 -> ImportError: cannot import name 'extract_review_constraints'; passes at the tip
• live read-only agentdescent github review --pr 774 --owner ThinkFlowLab --repo agentdescent --json -> head a1af3a53..., checks_state: success, ready: true, requires_human_click: true; no write, no approve
• risk_gate.py --pr 774 -> T3 (398 changed lines / 5 files > 250/12), so the owner's explicit merge click is required
  Not run:
• the social step of mkdocs build --strict (fonts.google.com unreachable from this host); CI runs it and is green at this tip
  Findings:
• Blocking: a historical CHANGES_REQUESTED never clears (agentdescent/github_surface.py:665-671, :717-718). _review_counts() counts every review event, so a reviewer who requests changes and then approves still blocks: probe with reviews CHANGES_REQUESTED + APPROVED over green checks -> ready: false, blockers ['1 reviewer(s) requested changes', '1 unresolved blocking review constraint(s)']. That is the workflow this repo actually uses ("Please re-review"), so the packet's headline answer is wrong exactly where it is used. Fix: keep the latest review per author (or drop a change request once that reviewer later approves) before counting, and apply the same rule to the constraint list.
• Non-blocking: the constraint docstring does not match the code (agentdescent/github_surface.py:309 vs :331). It promises "other comments are suggestions unless they use a must/blocker phrase", but _ACTION also matches please/needs/fix/add/update/remove/rename/ensure/handle/avoid, so a COMMENTED "Please add a test" becomes blocking and "maybe add a docstring" becomes blocking docs. Either narrow the promotion to the documented phrases or say so in the docstring and docs/github.md:121-125.
• Nit: tests/test_github_publisher.py:299 still has no trailing newline (the same nit as the previous review).
• Body numbers: the -n 12 run reports 21 failed / 10 errors, my serial run reports 24 failed / 10 errors; all 24 reproduce on main, so the claim direction holds, but a serial run should be described as 24.
• Fixed in a1af3a5: docs/github.md "What this is not yet" no longer calls review ingestion a future PR.
  Verdict: FAIL

[Birfy]

Verdict: PASS

Tip SHA: a1af3a5

New commit since the PASS at 821cd4b is docs-only (docs/github.md +5/-4, the "What this is not yet" section now reflects that review ingestion ships here). Code/tests unchanged from the previously reviewed tip; CI green at this tip. risk_gate: T3 (405 lines) — waiting for Danyang's merge click.

[Birfy]

Verdict: PASS

Tip SHA: 65c57a4

New commit since the PASS at a1af3a5 is only a merge of main. The PR's own changes against main are line-for-line identical to the previously PASSed tip (+398/-7, 5 files). Required CI is green and the PR is CLEAN.

risk_gate: T3 (size 405 lines > 250), so this waits for the owner's click; not merging.