docs(agents): state the CI contract every agent and routine follows by cdeust · Pull Request #973 · cdeust/Cortex

cdeust · 2026-11-10T12:14:32Z

Why

The scheduled "CI autopilot" routines were written before the review contract. On 2026-11-10 they measured branches against the main branch and tried to rebase them with a forced push, commented on approved pull requests (#968) and opened pull requests while another was in flight (#971, #972). Their prompt cannot be edited from an agent session, but it tells them to read CLAUDE.md and docs/ and to apply the repository's standards.

What

docs/agent-guidance.md: a section "CI contract for agents and routines" placed after "Review rounds". It holds only the rules "Review rounds" does not: no push while a review runs, no forced push, no comparison with the main branch, one pull request in flight, no comment after an approve, owner decisions left alone, no agent writes a Verdict: line. Both sections are said to win over a less restrictive routine prompt and never to widen one.
CLAUDE.md: one line in the non-negotiables that points to them.
CHANGELOG.md: the entry.

No code, no workflow. The same contract is merged in cdeust/ai-architect-mcp-spec#201, cdeust/claude-mods#68, cdeust/session-optimizer#107 and cdeust/zetetic-team-subagents#245; this text carries their review notes.

Checks

scripts/check_doc_claims.py: OK. tests_py/scripts/test_check_doc_claims.py and test_docs_index_links.py: 155 passed.

Metric

Comments posted by a routine on an approved pull request, pull requests opened while one is in flight, and "behind main" comments: expected to fall to zero from the routine's next pass. Not verifiable before that pass.

Generated by Claude Code

The scheduled routines were written before the review contract: on 2026-11-10 they measured branches against the main branch and rebased them with a forced push, commented on approved pull requests (#968) and opened pull requests while another was in flight (#971, #972). Their prompt tells them to read CLAUDE.md and docs/ and to apply the repository's standards, so the rules "Review rounds" does not hold yet are written next to it, and both are said to win over a less restrictive routine prompt. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_018kyZYsWnKSjpX4oNV19PCF Signed-off-by: Claude <[email protected]>

chatgpt-codex-connector · 2026-11-10T12:14:45Z

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-10T13:17:31.608150Z	`bc52c62`	New commits
🔒 Security Review	✅ Completed 2026-11-10T13:18:48.064879Z	`bc52c62`	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

claude · 2026-11-10T12:15:29Z

Claude finished @cdeust's task in 2m 9s —— View job

Review 1 of 3 done

Read the PR diff and the resolver and review workflows
Ran five reviews: documentation accuracy, code quality, security, performance and test coverage
Posted the review: docs(agents): state the CI contract every agent and routine follows #973 (comment)

I found no Blockers and posted three Notes. I did not run check_doc_claims.py myself; the reviews traced its patterns against the new text instead.

claude · 2026-11-10T12:17:34Z

Review 1 of 3 — PR #973

Five reviews ran on the diff: documentation accuracy, code quality, security, performance and test coverage. None found a Blocker.

What I checked against the code:

Rule 1 matches the resolver. _review_approves in .github/workflows/pipeline-post-merge.yml:366-398 reads only claude[bot] Bot comments that link a successful claude-review.yml run of the exact head, and takes the latest whole line that matches ^Verdict: (approve|block).
Rules 2 and 3 match the review budget. claude-review.yml uses cancel-in-progress: false, and scripts/ci_review_budget.py counts runs by branch and PR number, so a forced push does not reset the budget.
The CLAUDE.md bullet is in the PR head. The CHANGELOG line that says CLAUDE.md points to the section is true.
No check or test reads anything the PR changes. check_doc_claims.py finds no count claims in the new section, and test_docs_index_links.py has no index entry the new section must add.

Notes, no action before merge

docs/agent-guidance.md:170: the claim that the review verdict decides the merge leaves out the low-risk Dependabot merge, which needs no review (ADR-1126, pipeline-post-merge.yml:434-458). It also leaves out the hold on a title that says "do not merge" (:461-472).
docs/agent-guidance.md:156-158 / :170-173: a PR cut after its third review gets a new head that has no review, and rule 1 forbids a hand merge. It therefore waits for the owner's claude-rereview label, and neither section says so.
docs/agent-guidance.md:172-173: the ban on writing a Verdict: line is the only guard. The resolver accepts any claude[bot] comment that links the head's review run, sorts by updated_at, and does not check that the review step posted the comment. Hardening the code belongs in a follow-up PR.

Verdict: approve

… (ADR-1130) (#975) The resolver counts a verdict only when its comment links a successful review run of the head (ADR-1121). The prompt asked for one final verdict line and did not say where. A review posted with gh pr comment carried the verdict and no link, the tracking comment carried the link and no verdict, and the resolver held the merge: #973, approved at 12:17 UTC and green at 12:36, was not merged (resolver run 42816975550, "Claude has not posted a verdict on this head"). The prompt now gives the run's link and says to put it just before the verdict line in every comment that carries it. The resolver is unchanged. Claude-Session: https://claude.ai/code/session_018kyZYsWnKSjpX4oNV19PCF Signed-off-by: Claude <[email protected]> Co-authored-by: Claude <[email protected]>

Notes of review 1 of #973, taken in one push because that review's verdict cannot be read by the resolver (its comment does not link the run, fixed for later reviews by ADR-1130, #975): the low-risk Dependabot merge and the "do not merge" title, and what a pull request cut down after its third review waits for. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_018kyZYsWnKSjpX4oNV19PCF Signed-off-by: Claude <[email protected]>

…agents Signed-off-by: Claude <[email protected]> # Conflicts: # CHANGELOG.md

claude · 2026-11-10T13:21:27Z

Claude finished @cdeust's task in 1m 57s —— View job

Review 2 of 3 done

Found the commits pushed after 90760cd: c154914 changes rule 1, and merge bc52c62 adds nothing to the PR diff
Checked the earlier Blockers: review 1 found none
Ran five reviews on the new commits: documentation accuracy, code quality, security, performance and test coverage
Posted the review: docs(agents): state the CI contract every agent and routine follows #973 (comment)

I found no Blockers and posted three Notes. The new rule 1 text matches what the resolver does (pipeline-post-merge.yml:383-384, :434-477). I did not run check_doc_claims.py or the doc tests; the reviews traced their patterns against the new text instead.

Verdict: approve

claude · 2026-11-10T13:23:18Z

Review 2 of 3 — PR #973

Review 1 found no Blockers. This review covers only what was pushed after 90760cd: commit c154914, which changes rule 1 in docs/agent-guidance.md:170-177, and merge bc52c62, which adds nothing to the PR diff (git diff origin/main...HEAD still shows only CHANGELOG.md, CLAUDE.md and docs/agent-guidance.md, +44/-0). Five reviews ran: documentation accuracy, code quality, security, performance and test coverage. None found a Blocker.

What I checked against the code:

Low-risk Dependabot merge, no review: true. _is_low_risk in .github/workflows/pipeline-post-merge.yml:434-458 decides it, and the skip is at :474-477.
"do not merge" title: true. The check at :466 ignores case, and it runs before both the review path and the low-risk path.
PR cut down after its third review: true. Its new head has no review, so _review_approves holds the merge (:383-384). The cap is 3 and the bypass label is claude-rereview (scripts/ci_review_budget.py:36-37, ADR-1119).
Checks: check_doc_claims.py patterns need a number followed by a unit, so "Two cases" and "third review" do not match. No heading changed, so test_docs_index_links.py is not affected. I did not run either.

Notes, no action before merge

docs/agent-guidance.md:156-157 says "The accepted part merges" after the third review, but rule 1 (:175-177) now says a cut-down head waits for the owner's label. A refinement PR could make the bullet say the same.
docs/agent-guidance.md:177: adding the label does not start a review by itself. claude-review.yml:7 does not run on labeled, so the cut-down head also needs a reopen or a push.
docs/agent-guidance.md:174: the hold and do-not-merge labels also stop a merge (pipeline-post-merge.yml:467-473), and only the title is named.

View job run
Verdict: approve

cdeust mentioned this pull request Nov 10, 2026

ci(review): the comment that carries the verdict links the review run (ADR-1130) #975

Merged

cdeust mentioned this pull request Nov 10, 2026

ci(review): the comment that carries the verdict links the review run (Cortex ADR-1130) cdeust/ai-architect-mcp-codebase#497

Merged

Merge remote-tracking branch 'origin/main' into docs/ci-contract-for-…

bc52c62

…agents Signed-off-by: Claude <[email protected]> # Conflicts: # CHANGELOG.md

github-actions Bot merged commit e8a7c53 into main Nov 10, 2026
18 checks passed

Navigation Menu

Repository navigation

docs(agents): state the CI contract every agent and routine follows - #973

docs(agents): state the CI contract every agent and routine follows#973
github-actions[bot] merged 3 commits into
mainfrom
docs/ci-contract-for-agents

cdeust commented Nov 10, 2026

Uh oh!

chatgpt-codex-connector Bot commented Nov 10, 2026 •

edited

Loading

Uh oh!

claude Bot commented Nov 10, 2026 •

edited

Loading

Uh oh!

claude Bot commented Nov 10, 2026

Uh oh!

claude Bot commented Nov 10, 2026 •

edited

Loading

Uh oh!

claude Bot commented Nov 10, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

cdeust commented Nov 10, 2026

Why

What

Checks

Metric

Uh oh!

chatgpt-codex-connector Bot commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review 1 of 3 done

Uh oh!

claude Bot commented Nov 10, 2026

Review 1 of 3 — PR #973

Uh oh!

claude Bot commented Nov 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review 2 of 3 done

Uh oh!

claude Bot commented Nov 10, 2026

Review 2 of 3 — PR #973

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chatgpt-codex-connector Bot commented Nov 10, 2026 •

edited

Loading

claude Bot commented Nov 10, 2026 •

edited

Loading

claude Bot commented Nov 10, 2026 •

edited

Loading