Enhance AGENTS.md formatting warnings to prevent recurring CI failures

[Copilot]

AI agents repeatedly commit unformatted Go code, causing 5 identical CI failures in one day. The existing make agent-finish warnings in AGENTS.md are insufficiently prominent.

Changes

Critical Requirements Section

• Added "⚠️ MANDATORY PRE-COMMIT VALIDATION ⚠️" subsection with visual emphasis
• Explained consequences: CI blocks automatically, cannot be disabled
• Added file-type-specific commands (*.go → make fmt, *.md → make recompile, *.cjs → make fmt-cjs)
• Provided fast-path alternative: make fmt + make test-unit (replaces 10min make agent-finish)

Quick Reference Section

• Added "🚨 CRITICAL - Pre-Commit Checklist" with numbered steps
• Moved from buried bullet point to prominent subsection

Example

Before:

## Critical Requirements

**ALWAYS RUN AGENT-FINISH BEFORE COMMITTING:**

After:

## Critical Requirements

### ⚠️ MANDATORY PRE-COMMIT VALIDATION ⚠️

**🚨 BEFORE EVERY COMMIT - NO EXCEPTIONS:**

**Why this matters:**
- **CI WILL FAIL** if you skip this step - this is automatic and non-negotiable
- This has caused **5 CI failures in a single day** - don't be the 6th!

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[CI Failure Doctor] Recurring CI failure: Check Go formatting step fails - 5th occurrence today</issue_title>
<issue_description># 🏥 CI Failure Investigation - Run githubnext/gh-aw#29602

Summary

⚠️ RECURRING PATTERN - This is the 5th occurrence of this failure type today.

The CI workflow failed because Go code was not properly formatted before committing. The "Check Go formatting" step in the lint-go job detected unformatted Go files.

Failure Details

• Run: #21012388902 (Run githubnext/gh-aw#29602)
• Commit: 030f506d2354f66024247585b91e19301f9ddbf6
• PR: Change codespace installation callout from CAUTION to TIP in quickstart #9997 - "Change codespace installation callout from CAUTION to TIP in quickstart"
• Trigger: push to main branch
• Author: Copilot (AI agent)
• Failed Job: lint-go (Job githubnext/gh-aw#60410207744)
• Failed Step: "Check Go formatting" (step 5)
• Time: 2026-01-14 22:37:59 UTC

Root Cause Analysis

Primary Cause

The AI agent (Copilot) committed code changes without running the mandatory pre-commit command: make agent-finish (or at minimum make fmt).

Pattern Recognition

This failure matches the known pattern GO_FORMAT_CHECK_FAILED with high confidence:

• Pattern first seen: 2026-01-14 06:08:42 UTC
• Last occurrence (before this): 2026-01-14 07:51:41 UTC
• Total occurrences today: 5
• Pattern signature: lint-go job → Check Go formatting step failure

Why This Keeps Happening

1. AI agents are not consistently following the documented workflow that requires running make agent-finish before every commit
2. No automated enforcement - there are no pre-commit hooks or branch protection rules that enforce formatting
3. False sense of completion - the AI agent successfully completes its task (e.g., doc changes) but doesn't realize it needs to format code

Suspicious Commit Characteristics

The PR #9997 only changed 2 files:

• docs/src/content/docs/setup/quick-start.md (the intended documentation change)
• .github/workflows/glossary-maintainer.lock.yml (regenerated workflow file)

However, the commit statistics show hundreds of Go files modified. This suggests either:

• A merge commit that brought in unformatted changes from another branch
• A grafted commit in a shallow clone

The formatting check caught the issue regardless of the source.

Failed Jobs and Errors

Job: lint-go

Status: ❌ Failed
Duration: ~17 seconds (22:38:03 - 22:38:20)
Failed Step: Check Go formatting (step 5)

Step Flow:

✅ 1. Set up job
✅ 2. Checkout code
✅ 3. Set up Go
✅ 4. Report Go cache status
❌ 5. Check Go formatting (FAILED)
⏭️ 6. Install golangci-lint (SKIPPED)
⏭️ 7. Run golangci-lint (SKIPPED)
⏭️ 8. Lint error messages (SKIPPED)

Expected Error (based on pattern):

❌ Code is not formatted. Run 'make fmt' to fix.
Unformatted files:
[list of files]

To fix this locally, run:
  make fmt

Investigation Findings

Historical Context

This is part of a systematic issue where AI agents repeatedly commit code without proper formatting:

Date	Run ID	Commit	PR	Author
2026-01-14 06:08	20984232736	b1b5f4b	#9903	Copilot
2026-01-14 06:14	20984290612	99c636f	#9894	Copilot
2026-01-14 06:28	20984405453	(unknown)	(unknown)	Copilot
2026-01-14 07:51	20986559929	(unknown)	(unknown)	Copilot
2026-01-14 22:37	21012388902	030f506	#9997	Copilot

Pattern: All failures are from Copilot (AI agent) commits.

Impact Assessment

• Severity: Medium (doesn't break functionality, but blocks CI)
• Impact: High (all CI checks fail, blocks other PRs, wastes CI resources)
• Urgency: High (recurring issue needs systematic fix)
• Time to fix: ~5 minutes (run make fmt and push)

Recommended Actions

Immediate Fix (For This Specific Failure)

# Fix the formatting issue
make fmt
git add .
git commit -m "Fix Go formatting"
git push

Short-term Prevention (Reduce Recurrence)

• Strengthen AI agent instructions: Add more prominent warnings in AGENTS.md about mandatory make agent-finish
• Add validation check: Create a reminder in the AI agent prompt about pre-commit requirements
• Update PR template: Add a checklist item for make agent-finish

Long-term Solutions (Eliminate Recurrence)

• Add pre-commit hooks: Install Git hooks that automatically run make fmt before commits

  # .git/hooks/pre-commit
  #!/bin/sh
  make fmt
  git add .

• Auto-formatting PR workflow: Add a GitHub Action that automatically formats co...

• Fixes [CI Failure Doctor] Recurring CI failure: Check Go formatting step fails - 5th occurrence today #10004

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.