docs(#6757): document credential context separation in install pkg

[fullsend-ai-coder]

Summary

Documents the credential context separation between the test suite's e2e installation token and dispatch's per-repo GITHUB_TOKEN in the pkg/behaviourtest/drivers/install package. This knowledge gap caused both a human developer (PR #6703) and an autonomous agent (PR #6709) to independently attempt the same incorrect suite-side GetCollaboratorPermission polling approach for #6701.

Related Issue

Closes #6757

Changes

• Add doc.go with package-level documentation explaining the two-token model: the suite's e2e GitHub App installation token vs dispatch's per-repo GITHUB_TOKEN, their independent permission propagation graphs, and why suite-side permission probing is unreliable
• Add inline note on awaitCreation in ensure.go warning against adding GetCollaboratorPermission polling, with a pointer to doc.go
• Add "Credential context separation" paragraph in docs/guides/dev/behaviour-testing.md under the "Repo allocation" section, cross-referencing the package doc and issue behaviourtest: wait for permission propagation after pool repo recreate (dispatch sees no role, matrix empty) #6701

Testing

• go build and go vet pass on the changed package
• go test ./pkg/behaviourtest/drivers/install/... passes
• gofmt produces no changes
• lychee and lint-docs-links pass on the changed markdown
• No production code changes — documentation only

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• No secrets or sensitive data in the diff

---

Closes #6757

Post-script verification

• Branch is not main/master (agent/6757-credential-context-docs)
• Secret scan passed (gitleaks — dc0f8e15488fc816f9464c63e644e17de549edd1..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[github-actions]

Site preview

Preview: https://21773da4-site.fullsend-ai.workers.dev

Commit: 440cfd4d5655194be6326f00b806e695c4b88881

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:29 PM UTC · Completed 6:43 PM UTC

Commit: 440cfd4 · View workflow run →

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Risk Assessment: moderate (2/5)

Details

Small documentation-only PR by a bot adding package docs and guide entries with no protected paths, security concerns, or dependency changes; moderate churn history on touched files is the only uplift signal.

[fullsend-ai-review]

Looks good to me

---

Labels: PR adds documentation for e2e behaviour test credential context separation

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:01 PM UTC · Completed 12:08 PM UTC

Commit: 440cfd4 · View workflow run →

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

[fullsend-ai-retro]

Retro: PR #6758 — Document credential context separation in install pkg

The workflow for PR #6758 was a clean end-to-end success demonstrating the full retro-to-merge pipeline.

Timeline

1. Retro agent created issue #6757 identifying that both a human (PR #6703) and a code agent (PR #6709) independently attempted the same incorrect fix for #6701 due to undocumented credential context separation.
2. Triage agent classified it as medium-severity documentation (cost: $0.62, run 33267606127).
3. Code agent produced 55 lines of well-structured documentation across 3 files — a new doc.go, an inline comment on awaitCreation, and a guide section — in a single iteration with no rework (cost: $2.17, run 33267867307).
4. Review agent approved with zero findings ("Looks good to me"), risk moderate (2/5), using opus at high effort (cost: $3.59, run 33268317345).
5. Human reviewer (rh-hemartin) approved with no comments 6 days later.
6. PR merged 10 days after creation.

Total agent cost: $6.38. Rework iterations: 0.

Assessment

This is the system working as designed — a retro agent identified a knowledge gap that caused repeated incorrect fixes, and the pipeline produced quality documentation to close that gap.

Evidence for existing issues

• #6891 (pre-flight scope heuristic): This PR is a strong data point. The review agent used opus at high effort ($3.59) on a 55-line docs-only PR and produced zero findings. A scope heuristic detecting docs-only/trivially-scoped PRs could have routed this to a lighter model or lower effort, potentially reducing review cost by 3-5x.
• #5289 (autonomy readiness for docs-only): This PR matches the same pattern — the review agent fully covered the human review (both approved, zero inline comments from either). Human review added no incremental signal but added 6 days of latency.

No new proposals

The improvement opportunities identified in this retro are already tracked by existing open issues. No new proposals are warranted.