docs: document CI efficiency expectations for agents

[Yuxin-Qiao]

Agent instructions require full checks but do not explain how to preserve verified incremental builds or avoid repeating expensive validation on unchanged code. Add a CI Efficiency section to AGENTS.md that asks contributors to assess cache/job impact, retain required coverage and cache safeguards, and report measured results separately from predictions.

The guidance keeps required checks intact and reserves repeated cold/warm and multi-toolchain proof experiments for relevant changes. It does not change workflows or claim a runtime speedup.

Real agent behavior proof

An actual Codex CLI agent completed the developer handoff for this PR at head 1ea3f1af7c59205fc45a22a879da1071e3a8ba31. Its task permitted justified local validation and asked it to decide what additional checks were needed; the prompt did not prescribe skipping full tests. The agent read the modified root instructions, inspected CI/cache/path-gate code, independently matched the downloaded results against live GitHub, and applied AGENTS.md:35 to retain successful full-suite evidence without starting another full run solely for reporting.

Recorded session and provenance · Actual terminal events · Agent handoff · Task prompt

Actual local terminal results in the recorded session:

PASS: clean checkout and git diff --check for current base/head
Actual base/head name-status: M\tAGENTS.md
PASS: both production gates match actual PR diff and hosted job scope
PASS: all cache-context inputs and both path-gate blobs equal merged base; AGENTS.md outside context/build-input graph
PASS: recorded snapshot head, run URL, attempt, status, all 9 jobs, timestamps and step results match live GitHub
PASS: cache fallback and full-inventory events independently matched live job 114125028480 in run 38022055294

The agent process exited 0; all 20 shell commands succeeded. The public derivative retains 17 command events and the agent's decisions; three private-memory command events, local/session identifiers and usage metadata are omitted, and long output excerpts are explicitly marked. Originals are preserved locally. The evidence documents live on a separate fork branch, leaving this PR's diff at one file, +10 lines.

Scope: this is one real handoff task after completed CI, not a controlled before/after prompt study, a new local full-suite run, or a guarantee about future agent behavior. No tracked files, gates or cache safeguards were changed by the agent session, and it made no measurable speedup claim.

Validation

• CI run 38022055294, attempt 1 passed for the reviewed PR head: lint, macOS full discovered inventory, plugin engine A/B goldens, Swift 6.2 compatibility build, both Linux glibc lanes and the aggregate check. GitGuardian passed separately. Musl and main-only cache pruning were skipped by existing policy.
• Actual macOS logs show 1,651 discovered selections and 216 first-pass successful groups, using two workers. Bounded log excerpts and job timings separate queue and execution.
• Both macOS lanes downloaded a cache but used a conservative clean fallback for changed build-input paths. This run proves required validation passed, not an incremental-build performance improvement.
• Local whitespace/scope checks and both actual-diff production path gates passed. AGENTS.md is outside compiled-cache context inputs; this edit changes no workflow or cache implementation.
• No local Swift build/test repeat was started solely to prepare this report; the successful hosted full-inventory run is identified separately above.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-10T03:53:49.035909Z	1ea3f1a	PR opened

ℹ️ 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.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

This PR documents how agents should preserve incremental builds, retain required checks, and substantiate CI performance claims.

Example: An agent prepares a handoff for head 1ea3f1a after successful hosted validation.

• Before: The instructions require full checks but leave repeated validation on unchanged inputs unspecified.
• After: The agent retains the successful validation evidence and avoids another full run solely to prepare the report.

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	Focused, useful guidance with directly relevant CLI behavior evidence, passing hosted validation and no actionable findings.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (linked_artifact): The published Codex CLI session at the reviewed head shows an actual handoff applying the changed root guidance, retaining successful hosted validation and avoiding a reporting-only repeat; this resolves the earlier proof request without establishing a general speedup.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Development agents lack explicit guidance about preserving verified builds and avoiding repeated expensive checks solely for reporting.
Reason: The focused addition explains existing safeguards and validation obligations without changing product defaults or weakening CI coverage.

Merge readiness

✅ Ready for maintainer review

This PR adds useful guidance consistent with current CI safeguards, with no actionable patch defects; repository policy does not permit closing it.

Priority: P3
Reviewed head: 1ea3f1af7c59205fc45a22a879da1071e3a8ba31

Before merge

None.

Findings

None.

Agent review details

How this fits together

Root contributor instructions guide development agents from change inspection through local validation and handoff; existing workflow and cache scripts continue to determine CI execution.

flowchart TD
A[Development task] --> B[Root agent instructions]
B --> C[Inspect change and CI contracts]
C --> D[Focused validation]
D --> E[Required final checks]
E --> F[Evidence based handoff]

Loading

Technical review

Best possible solution:

Land the focused guidance while preserving existing CI gates, cache safeguards and required validation.

Do we have a high-confidence way to reproduce the issue?

This is a documentation improvement; the recorded handoff demonstrates the intended agent behavior rather than reproducing an application defect.

Is this the best way to solve the issue?

The root instructions are the appropriate location, and the addition preserves required checks while clarifying when repetition and performance experiments are justified.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against c2f22ccf8751.

Provenance checked

• Contributor validation guidance keeps the original intent (6e75866: Repository guidelines establish required validation; subsequent guidance in f1ac8bf favors stable test seams.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

• Pinned change and current main: The introduced diff adds only the ten-line CI Efficiency section; fetched main does not contain it. Existing required-check instructions remain intact. (AGENTS.md:30, 1ea3f1af7c59)
• Existing CI contracts: The macOS gate explicitly requires macOS tests and Linux glibc builds for AGENTS.md. Cache code verifies context, contents, modes and symlinks, and falls back conservatively when build-input paths change; the guidance preserves these contracts. (Scripts/ci_macos_test_gate.sh:45, 1ea3f1af7c59)
• Recorded agent behavior: The published CLI event record shows the agent reading the modified instructions, checking the actual diff and production gates, verifying hosted results, and explicitly applying line 35 to avoid a reporting-only full-suite repeat. The prompt permitted justified local validation without prescribing that decision. https://github.com/Yuxin-Qiao/CodexBar/blob/480495f50db0bd18f6261025c228d494acfde7fd/docs/proofs/ci-efficiency-agent-session/session.jsonl. (docs/proofs/ci-efficiency-agent-session/session.jsonl, 480495f50db0)
• Validation for reviewed head: Live REST results confirm successful CI attempt 1 for the reviewed head, including lint, macOS tests, compatibility compilation, both glibc lanes and aggregate CI; musl and cache pruning were skipped. https://github.com/steipete/CodexBar/actions/runs/38022055294. (.github/workflows/ci.yml, 1ea3f1af7c59)
• Feature history and local limit: Path history identifies Peter Steinberger's longstanding contributor guidelines and recent CI safeguards, alongside Yuxin Qiao's merged cache and path-gate work. Some older CI blobs were unavailable with lazy fetching disabled, preventing targeted CI blame; AGENTS.md history and blame were readable. (AGENTS.md:23, c2f22ccf8751)

Likely related people:

• Peter Steinberger: Raw commit 0677030 adds AGENTS.md:22 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 06770308831e; files: AGENTS.md)

Review metrics

Metric	Value	Why it matters
Patch scope	Documentation +10/-0; production and tests +0/-0	The small instruction addition introduces no workflow, cache-context or CI job-scope changes.

Labels

Label changes:

• add P3: Low-risk contributor documentation with no runtime or CI implementation changes.
• add proof: sufficient: Contributor real behavior proof is sufficient.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: Low-risk contributor documentation with no runtime or CI implementation changes.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only; repair and merge need explicit maintainer commands such as @clawsweeper autofix or @clawsweeper automerge.

History

Review history (1 earlier review cycle)

• reviewed 2026-10-10T03:54:45.510Z sha 1ea3f1a :: needs real behavior proof before merge. :: none

Reviewed October 10, 2026, 3:40 AM ET / 07:40 UTC (Revision 2).