docs(#5372): add escalation ladder for core agent changes

[fullsend-ai-coder]

Summary

Add a prove-it escalation ladder that defines a structured path for teams to follow before deriving or replacing a core agent role (triage, code, review, fix, retro, prioritize). The ladder has four levels — configure, contribute, derive, replace — each with concrete evidence requirements for escalation.

Related Issue

Closes #5372

Changes

• New doc page at docs/agents/topics/escalation-ladder.md with four escalation levels, evidence requirements at each step, and a prove-it checklist
• Cross-links added from default-vs-custom.md, bring-your-own-agent.md, customizing-agents.md, and building-custom-agents.md
• Sidebar entry added under the Agents section in VitePress config

Testing

• Link check passes (lychee --offline: 22 total, 0 errors)
• Secret scan passes
• Gitlint passes
• make lint — pre-commit could not run in sandbox (network error); post-script runs it authoritatively

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Commits are signed off (DCO) — autonomous agent, exempt
• I wrote this contribution myself and can explain all changes in it

---

Closes #5372

Post-script verification

• Branch is not main/master (agent/5372-escalation-ladder)
• Secret scan passed (gitleaks — bf051001ad0ddc22d58e95d9d9b46d57e62e5b97..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 5:44 PM UTC · Completed 5:55 PM UTC
Commit: 7e0604a · View workflow run →

[github-actions]

Site preview

Preview: https://892d39bd-site.fullsend-ai.workers.dev

Commit: 62217e7b94a267210e3517a2fbc0d6b5dab83a2d

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Looks good to me

Previous run

Looks good to me

---

Labels: PR modifies only documentation files under docs/ and website config

[waynesun09]

Automated 3-agent review-squad pass (claude-coder, claude-researcher, grok). 5 findings survived verification and cross-checking against the repo's own docs (1 HIGH, 4 MEDIUM) — no CRITICAL findings, and link/anchor integrity across the new page is otherwise clean. See inline comments for details.

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 8:10 PM UTC · Ended 8:28 PM UTC
Commit: c9ed4f3 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:29 PM UTC · Completed 8:42 PM UTC
Commit: d61ad0f · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:14 PM UTC · Completed 1:32 PM UTC

Commit: 62217e7 · View workflow run →

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 1:28 PM UTC · Completed 1:46 PM UTC

Commit: 62217e7 · View workflow run →

[fullsend-ai-review]

Review skipped — this PR is already merged.

The /fs-review command only reviews open pull requests.

_{Posted by fullsend post-review check}

[fullsend-ai-retro]

Retro: PR #5373 — Escalation ladder docs

Timeline: Issue #5372 was filed by ascerra on Jul 20. Triage (run 29763872347) and code (run 29764233222) agents processed it within 14 minutes, producing PR #5373 with a new escalation-ladder.md page and cross-links in 4 existing docs. The review agent (run 29764769974) ran 4 sub-agents (correctness/opus, style/sonnet, intent/sonnet, docs-currency/sonnet), all returned 0 findings, and the agent APPROVED with "Looks good to me." Two days later (Jul 22), waynesun09 posted a 3-agent review squad analysis that found 5 real issues (1 HIGH, 4 MEDIUM) — all later confirmed valid when ascerra fixed them manually on Aug 4 (commit c9ed4f3, co-authored with Cursor). The PR merged Aug 9 after a second automated approval and human sign-off from ascerra.

Key finding: review quality gap. The review agent approved the PR while missing all 5 substantive findings the external review squad caught. The correctness sub-agent verified structural properties (anchors exist, identifiers match, specific technical claims match code) but did not verify semantic consistency within the new text. Three distinct failure modes:

1. Anchor resolution without content verification (findings docs: Add agent-compatible code problem document #1, docs: add agent infrastructure problem document #5): The sub-agent confirmed that customizing-agents.md#customization-examples exists as a heading but never read the content under it to verify it covers sandbox image layering. It read bring-your-own-agent.md but grepped for specific patterns rather than reading the merge-rules table that would have revealed the HIGH-severity claim inaccuracy.
2. No framing-vs-detail consistency check (finding Add problem areas: Tekton pipeline review, migration path, multi-tenancy #2): The Level 1 intro stated "no harness changes at all" while the table immediately below listed 5 extension points requiring harness YAML. The sub-agent verified individual table entries but never cross-checked them against the framing statement.
3. Procedural completeness gap (finding Use AI to help formalise intent after rapid local prototyping #4): The "How to contribute" section directed readers to open PRs without mentioning the vouch gate from CONTRIBUTING.md. No sub-agent was scoped to check whether procedural guidance is complete relative to repo processes.

Fix agent was not triggered. waynesun09's review was posted as COMMENTED (not CHANGES_REQUESTED), so the dispatch filter silently dropped it. The human fixed the issues manually 13 days later. This is already well-covered by existing issues: fullsend#5967 (dispatch filter), fullsend#3514 (processing human inline comments), and fullsend#3783 (triggerable from review comments).

Evidence for existing issues:

• agents#265 (cross-reference verified facts): This PR provides concrete evidence — the correctness sub-agent verified link existence but not semantic accuracy of the claims made about the linked content. Findings docs: Add agent-compatible code problem document #1 and docs: add agent infrastructure problem document #5 are textbook cases of misleading documentation narratives that cross-referencing would have caught.
• agents#528 (verify script/file references are resolvable): Finding docs: add agent infrastructure problem document #5 shows the gap extends beyond resolution to semantic accuracy — the reference resolved but the target content didn't cover the claimed topic.
• agents#427 (autonomy evidence for docs-only PRs): This PR provides counter-evidence. The review agent is competent at structural/mechanical docs review but missed all 5 findings on a prescriptive document making behavioral claims about system features. Autonomy for docs-only PRs should be qualified by document type.

No resource waste found. The failed dispatch on Aug 6 (run 31119802507) was a transient GitHub Actions CDN outage (503 Service Unavailable during action download). Post-merge review runs were correctly attributed to other PRs; concurrency groups are working as designed.

Agents repo: fullsend-ai/agents at commit c65eba2a790ebfff571a2a00a06fd1ec3524e934.

Proposals filed

• Correctness sub-agent should verify framing statements match their supporting content (in fullsend-ai/agents)