docs(#6781): promote forge-abstraction to explicit AGENTS.md bullet

[fullsend-ai-coder]

Summary

Adds a top-level bullet point for the forge-abstraction rule in the "How to work in this repo" section of AGENTS.md. The rule was previously listed only in the topic-guidance table, which required agents to infer that operations like setting repository variables are forge operations. This promotion mirrors the pattern used for other critical rules (DCO, coverage gate, CLI docs) and makes the architectural invariant — all forge operations must go through forge.Client — harder to miss.

Changes

• Added a Forge abstraction bullet after the Go coverage gate bullet and before the secrets bullet
• The new bullet explains the rule, names examples (GitHub API calls, setting repository variables, PR comments), and links to docs/contributing/forge-abstraction.md for full details

Testing

• lychee link checker passes on AGENTS.md
• Structural grep confirms forge.Client and forge-abstraction.md are present in AGENTS.md
• No trailing whitespace or end-of-file issues
• gitlint passes on commit message

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)

---

Closes #6781

Post-script verification

• Branch is not main/master (agent/6781-promote-forge-abstraction-bullet)
• Secret scan passed (gitleaks — e90aca92240c9d478677c6c5cc70e0a9b0edb95a..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:30 PM UTC · Completed 6:41 PM UTC

Commit: 2e6c223 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $2.85

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Risk Assessment: low (1/5)

Details

Docs-only 1-line addition to AGENTS.md by a bot author with no security-sensitive files, no CI changes, and no dependency changes. The change is trivially small and easily revertible.

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The change is well-justified (linked to Promote forge-abstraction to explicit AGENTS.md bullet point #6781, which explains the rationale for promoting the forge-abstraction rule to a top-level bullet, mirroring the existing pattern for DCO, coverage gate, and CLI docs rules). Human approval is always required for protected-path changes, regardless of context.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 10:08 AM UTC · Completed 10:16 AM UTC

Commit: 2e6c223 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.71

[fullsend-ai-retro]

Retro: PR #6783 — promote forge-abstraction to explicit AGENTS.md bullet

Timeline

This PR is the product of a clean retro-to-fix pipeline originating from PR #6779, where the code agent violated the forge-abstraction rule by shelling out to gh variable set instead of using forge.Client. The retro agent on PR #6779 correctly identified the root cause — the forge-abstraction rule was buried in the AGENTS.md topic-guidance table rather than promoted to an explicit bullet — and filed issue #6781.

Stage	Time (UTC)	Cost	Outcome
Triage	Aug 30, 18:17–18:21	$0.82	Severity: medium, category: docs
Code	Aug 30, 18:23–18:28	$1.42	1-line addition, correct on first try
Review	Aug 30, 18:30–18:41	$2.85	1 finding (protected-path), risk 1/5
Human approval	Sep 4, 09:57	—	rh-hemartin approved
Merged	Sep 4, 10:06	—	—

Total automation cost: $5.09 · Rework iterations: 0 · Time to merge: 5 days (human review latency on governance file)

Assessment

This workflow executed cleanly. The retro-to-fix pipeline worked exactly as designed: the retro agent identified a real root cause, the triage agent correctly categorized it, the code agent produced correct code on the first try (proper placement after the Go coverage gate bullet, matching the existing bullet pattern), and the review agent found the one appropriate finding (AGENTS.md is a protected governance file requiring human approval). Zero rework, no fix agent needed.

The 5-day human review latency is expected behavior — the requires-manual-review label was correctly applied because AGENTS.md is a protected path, and governance file changes warrant human judgment regardless of scope.

Evidence for existing issues (no new proposals needed)

• #6891 (pre-flight scope heuristic): This PR is another data point — $2.85 opus/high-effort review for a 1-line docs addition that yielded only the expected protected-path finding. A scope heuristic could have downgraded to a lighter model/effort.
• #3317 (lightweight retro for bot-authored PRs): This retro is running on a bot-authored PR implementing a retro-generated issue. The full retro pipeline is producing no new proposals — a lightweight analysis or skip would have saved cost.
• #5289 (autonomy readiness for docs-only reviews): The review agent's protected-path finding was the only substantive concern, and the human approved without additional comments, confirming the agent's assessment was complete for this docs-only change.
• #4270 (review agent approval for AGENTS.md factual corrections): This PR is adjacent — it promotes an existing rule's visibility rather than correcting staleness, so it doesn't directly match Review agent should submit formal approval for AGENTS.md changes that only correct factual staleness without modifying conventions #4270's scope, but it's another case where human approval added no findings beyond the agent's review.