feat(github): validate exact pull-request heads

[Nobodyworld]

Summary

Begins issue #122 from the exact merged evidence baseline.

base branch: main
base SHA: dcb8e283f8445dd76f215a98023197d8ed5acab3
branch: feat/github-exact-pr-validation
current head: 4964f5a3d1fde424f4dd5d00f53910939a717b48
state: planning complete; product implementation not started

The current commit adds the living ExecPlan at .agent/execplans/009_github_exact_pr_validation.md.

Locked first slice

• authenticated operator requests validation by repository + PR number;
• server resolves one stable PR identity and exact current head SHA;
• existing repository allowlist and explicit approval gate remain authoritative;
• fresh execution uses the merged validate-switchboard@1 path without depending on feat(evidence): reuse exact validation evidence with local availability proof #121;
• server re-resolves the head before publication;
• moved heads become stale and never receive current-success claims;
• first publication surface is one bounded idempotent managed PR comment;
• GitHub credentials remain operator/server configuration only;
• no commands, argv, full logs, secrets, response bodies, environment dumps, absolute paths, or local artifact locations in normal payloads or publication.

Forbidden scope

• Checks API or status checks;
• webhook ingestion;
• workflow dispatch;
• automatic approval or merge;
• repository writes or code fixes;
• evidence reuse from feat(evidence): reuse exact validation evidence with local availability proof #121;
• MCP, browser, or desktop/RPA integration;
• artifact-byte upload/download;
• broad provider, credential, or identity redesign.

Planning validation

• Commitlint 29990883055 — success;
• CI 29990883049 — success.

The complete planning-head matrix passed, including lint/pre-commit, TODO validation, Mypy, full pytest, security, full-history Gitleaks, links, coverage thresholds, and strict browser tests.

Implementation gate

Keep this PR draft and unmerged throughout local implementation and connector review. Automated tests must use mocked GitHub transport and require no live credentials or network access. Final readiness requires focused security/idempotency/stale-head tests, a server-backed request-to-comment proof, complete local validation, and fully green hosted Commitlint and CI on the implementation head.

Closes #122 only after complete implementation, validation, connector review, and explicit owner-authorized merge.

[Nobodyworld]

Connector planning review complete.

The branch descends from exact merged base dcb8e283f8445dd76f215a98023197d8ed5acab3, contains only the living ExecPlan, and has successful Commitlint 29990883055 plus complete CI 29990883049.

The local implementation handoff must preserve these locked boundaries:

• manual authenticated request flow; no webhooks;
• managed PR comment only; no Checks API/status checks;
• existing repository allowlist and explicit approval gate;
• fresh validate-switchboard@1 execution independent of #121;
• re-resolve head before publication and fail moved heads stale;
• credentials remain server/operator configuration;
• mocked transport tests only; no live credentials/network in automation;
• no workflow dispatch, auto-merge, repository writes, artifact upload/download, MCP, browser, or RPA scope.

Keep PR #125 draft and unmerged. Stop and report rather than rebasing, force-pushing, or opening another branch/PR.

[Nobodyworld]

Connector planning addendum recorded on issue #122. The local implementation must treat it as part of the locked acceptance contract.

Key additions:

• first credential mode is an operator-configured fine-grained PAT via SWITCHBOARD_GITHUB_TOKEN with Metadata read and Pull requests read/write;
• explicit manual resolve/status/publish API flow; no background publisher;
• deterministic managed-comment marker and ambiguous-write recovery;
• the adapter resolves identity but does not fetch code or mutate canonical Git repositories;
• the exact PR head object must already exist in the operator-configured local repository or execution fails truthfully;
• fork heads are not silently substituted or fetched;
• narrow persistence is expected only for adapter lifecycle/idempotency/publication state.

Copy these decisions into .agent/execplans/009_github_exact_pr_validation.md during implementation and keep PR #125 draft.