docs: document PR title scope character restrictions

[fullsend-ai-coder]

Summary

• Adds scope character restriction documentation to the PR Conventions section of AGENTS.md
• Documents that scopes must match [\w$\.\-* ]* (the character class from pr-semantic.yaml's headerPattern)
• Explicitly notes that # and other special characters are not allowed in the scope position, and that issue references belong in the PR body instead

Context

PR #188 had its title fix(#187): ... rejected by the PR Semantic check because # is not in the allowed scope character set. A human had to manually rename the title to unblock CI. This documentation change prevents the same class of failure for future PRs from both agents and human contributors.

Testing

• Verified the documented character class matches the actual headerPattern regex in .github/workflows/pr-semantic.yaml
• Ran prettier check on AGENTS.md — passes

---

Closes #189

Post-script verification

• Branch is not main/master (agent/189-document-scope-restrictions)
• Secret scan passed (gitleaks — cb1efdbaf9d6188d148c463ecd47939cde4a02b9..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[github-actions]

Hey there and thank you for opening this pull request! 👋🏼

We require pull request titles to follow the Conventional Commits specification and it looks like your proposed title needs to be adjusted.

Details:

No release type found in pull request title "docs(#189): document PR title scope character restrictions". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/

Available types:
 - feat
 - fix
 - chore
 - docs
 - style
 - refactor
 - perf
 - test
 - revert

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure (validation failed after 1 iteration(s)) · Started 10:36 AM UTC · Completed 10:38 AM UTC

Commit: 977a762 · View workflow run →

Runtime: claude · Model: claude-sonnet-4-5@20250929 · Effort: high

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:38 PM UTC · Completed 12:50 PM UTC

Commit: 977a762 · View workflow run →

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

[fullsend-ai-retro]

Retro: PR #190 — docs: document PR title scope character restrictions

Timeline

PR #190 was the output of a fully automated retro → triage → code pipeline, completing in ~12 minutes with minimal human intervention:

1. 10:14 UTC — PR #188 merged, fixing review harness model but using fix(#187): in its title (scope violation requiring human fix).
2. 10:23 UTC — Retro agent on PR fix: pin review harness model to available Vertex AI version #188 created issue #189 proposing scope character restriction documentation in AGENTS.md.
3. 10:24–10:28 UTC — Triage agent processed issue Document PR title scope character restrictions in AGENTS.md #189 (medium severity), added ready-to-code label.
4. 10:29–10:35 UTC — Code agent created PR #190 adding one line to AGENTS.md documenting that #, @, and other special characters are not allowed in Conventional Commit scope positions.
5. 10:35 UTC — PR Semantic CI failed: the code agent used docs(#189): as the PR title — repeating the exact scope violation the PR was documenting.
6. 10:35 UTC — Review agent failed (run 34341001783): model claude-sonnet-4-5@20250929 (pinned by PR fix: pin review harness model to available Vertex AI version #188) is unavailable on the repo's Vertex AI deployment.
7. 10:36 UTC — Human (gashcrumb) approved, then fixed the PR title by removing the scope.
8. 12:36 UTC — Human merged PR docs: document PR title scope character restrictions #190.

Key Findings (evidence for existing issues)

1. Code agent scope violation pattern — evidence for fullsend-ai/fullsend#3391 and #5364

The code agent used type(#issue): format in two consecutive PRs on this repo — fix(#187): in PR #188 and docs(#189): in PR #190. Both times the # character in the scope caused PR Semantic CI failure and required human title edits. This is strong evidence that the code agent's post-script needs to validate PR titles against the repo's semantic PR rules before opening the PR.

2. Generic review failure messaging — evidence for fullsend-ai/fullsend#7023

The review agent posted "validation failed after 1 iteration(s)" without indicating the root cause (model unavailability). The actual error was that claude-sonnet-4-5@20250929 is not provisioned on Vertex AI. A more descriptive message (distinguishing runtime crashes from output validation failures) would have made the problem immediately actionable.

3. Model availability cascade — evidence for fullsend-ai/fullsend#6922, #6964, and #6883

The model misconfiguration saga (PRs #181 → #188 → #191 → #192 → #194) produced 5 PRs and multiple agent runs for a problem that needed 1 PR. The retro agent recommended a model version that was also unavailable, the code agent faithfully implemented the wrong recommendation, and the review agent couldn't review the fix PR (chicken-and-egg). Platform-level model availability validation and automatic fallback would have prevented this entire cascade. The issue is now resolved — PR #192 removed the model override, reverting to the base harness default.

What Went Well

• The automated pipeline (retro → triage → code) completed end-to-end in ~12 minutes with correct code output.
• The system is self-correcting: retro agents detected issues across multiple PRs and filed actionable proposals.
• The AGENTS.md update is well-targeted and should prevent future scope violations by code agents reading repo context.
• Human intervention was minimal (1 title fix, 1 approval, 1 merge).

No New Proposals

All improvement opportunities map to existing open issues in fullsend-ai/fullsend. The agents repo is fullsend-ai/agents@ec2f8a5b4369b844323ee1ee87c1d4a599a42817.