feat: acquire GitHub repositories for analysis

[vib-tools]

Summary

Update 01 implements GitHub App installation-authenticated repository acquisition and supplies Repository Analysis with a complete, commit-pinned snapshot.

The pull request includes the verified 19-file implementation commit plus a documentation-closure commit covering architecture, current status, delivery notes, verification evidence, rollout controls, and the Update 02 handoff.

Motivation

Before Update 01, Repository Engine could persist basic repository metadata, but the analyzer did not have authoritative repository evidence:

• no installation-authenticated private-repository acquisition;
• no exact default-branch commit pin;
• no exact root-tree identifier;
• no complete recursive path inventory;
• no bounded configuration-file contents;
• no complete snapshot contract for Repository Analysis.

Metadata-only evidence was insufficient for strong analyzer and Cloudflare-readiness decisions.

Architecture

Project / Repository request
→ Repository Engine public boundary
→ Connected Accounts public boundary
→ ephemeral GitHub App installation credential
→ GitHub Provider read-only acquisition
→ repository metadata
→ default branch head commit
→ exact commit tree
→ complete recursive inventory
→ bounded analysis-critical text
→ Repository Engine persistence
→ RepositoryAnalysisInput
→ Repository Analysis

Ownership

Responsibility	Owner
GitHub installation reference and ephemeral credential	Connected Accounts Module
GitHub HTTP calls	GitHub Provider
Repository metadata, snapshot, and analyzer input	Repository Engine
Detection and readiness decisions	Repository Analysis Engine
Project lifecycle and attachment	Project Engine

Delivered Behavior

• Resolves a connected GitHub App installation credential at runtime.
• Reads repository metadata with the installation credential.
• Resolves the default branch to an exact commit SHA.
• Resolves the commit's root tree SHA.
• Acquires a complete recursive Git tree.
• Fails closed for truncated or oversized/incomplete trees.
• Fetches bounded UTF-8 contents for selected analysis-critical files.
• Stores a versioned, commit-pinned snapshot.
• Prepares complete Repository Analysis input.
• Preserves current Quick Analysis behavior while enabling Update 02 evidence-based rules.

Snapshot Contract

schema_version
default_branch
commit_sha
tree_sha
snapshot_complete=true
complete path inventory
bounded selected text
acquisition limits
skipped-file reasons

The persisted commit SHA must match the snapshot commit SHA. Incomplete evidence is rejected.

Credential and Security Contract

• Installation access tokens are ephemeral.
• Raw tokens are not persisted.
• Raw tokens are not returned by API routes.
• Raw tokens are not included in snapshots, analysis results, jobs, or logs.
• Private source contents are not logged.
• Sensitive filenames and unsupported/binary content are excluded from bounded text acquisition.
• GitHub Provider remains an API wrapper and does not own YGIT business logic.
• Repository Analysis does not call GitHub directly.
• API routes do not call GitHub directly.

Error and Fail-Closed Behavior

• Missing/disconnected GitHub account: stop at Connected Accounts boundary.
• Invalid/expired installation credential: normalized provider/account failure.
• Missing repository/default branch: normalized repository error.
• Truncated or oversized recursive tree: REPOSITORY_SNAPSHOT_INCOMPLETE.
• Persisted/snapshot commit mismatch: analyzer input rejected.
• Provider outage: normalized provider-unavailable error.

Partial evidence cannot become deploy-ready evidence.

Database, Configuration, and Deployment Impact

Area	Impact
Database migration	None
New table	None
Environment/configuration mutation	None
Cloudflare API operation	None
Provider execution enablement	None
UI-V2	None
Production deployment	None
AG-002 runtime wiring	None

WORKER_PROVIDER_EXECUTION_MODE=disabled remains unchanged.

Scope

Implementation base: d2ad741c0ee48bf3eb3887a3357f6f450825c99a
Implementation commit: cb796401afe8be64eb311a45e566fc315a13a00c
Implementation branch: feature/github-repository-acquisition-analyzer-input-v1
Implementation files: 19

The documentation closure changes Markdown and VERSION.json only. It does not modify implementation source.

Verification

Ruff 0.15.20: PASS
Update 01 focused tests: 27 passed
Full test suite: 609 passed
Compileall: PASS
Smoke --skip-db: PASS
Release gate --skip-db: PASS
Remote implementation branch SHA: VERIFIED
Working tree after implementation push: CLEAN

The documentation patch reruns compileall, the full test suite, smoke, release gate, JSON parsing, exact-scope checks, and temporary-index whitespace checks before commit.

Not Executed

• Live GitHub App installation-token acquisition.
• Live private-repository tree acquisition.
• Live PostgreSQL persistence verification.
• Live Redis worker execution.
• Live Cloudflare API execution.
• Real Cloudflare Pages deployment.
• Production redeploy.

Rollout

1. Keep this PR Draft.
2. Require Backend CI / Validate on the final head.
3. Review exact scope, security boundaries, and documentation.
4. Mark Ready only after explicit authorization.
5. Merge only after separate explicit authorization.
6. Perform controlled live GitHub validation after merge.
7. Keep Cloudflare provider execution disabled until its separate gate.

Rollback

Before merge, close the Draft PR and preserve the feature branch for evidence.

After merge, use a reviewed revert of the merge commit. No database rollback is required.

Update 02 Handoff

Update 02 will use the new snapshot evidence for:

• framework/language confidence and evidence;
• monorepo and application-root resolution;
• package-manager and lockfile correlation;
• install/build command resolution;
• output-directory resolution;
• environment-variable reference detection without values;
• Cloudflare readiness states and blocking reasons;
• deep-analysis completion;
• Project reattachment after recalculation.

Reviewer Checklist

• Final CI head passes.
• Exact implementation and documentation scope reviewed.
• No raw token persistence or exposure.
• No migration.
• No Cloudflare execution or provider enablement.
• Truncated/incomplete snapshots fail closed.
• Provider/engine boundaries remain intact.
• Live-validation limitations are explicit.
• Update 02 work is not mixed into Update 01.