feat: acquire GitHub repositories for analysis

CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## Unreleased — Update 01: GitHub Repository Acquisition + Analyzer Input — 2026-07-25
+
+### Added
+
+- Ephemeral GitHub App installation-credential acquisition through the Connected Accounts public boundary.
+- Installation-authenticated repository metadata acquisition for public and private repositories authorized to the installation.
+- Default-branch head resolution to an exact commit SHA.
+- Exact commit-tree resolution and complete recursive Git-tree acquisition.
+- Bounded UTF-8 contents for analysis-critical repository files.
+- Versioned, complete, commit-pinned repository snapshot persistence.
+- Repository Analysis input containing commit SHA, tree SHA, snapshot version, completeness state, full path inventory, and bounded text evidence.
+- Fail-closed errors for inaccessible repositories, missing default branches, incomplete/truncated trees, and invalid installation credentials.
+- Update 01 architecture, completion, verification, and PR-control documentation.
+
+### Changed
+
+- Repository Engine now obtains the GitHub installation credential through Connected Accounts instead of relying on unauthenticated metadata-only acquisition.
+- GitHub Provider now accepts an installation access token for repository reads and resolves metadata, commit, tree, inventory, and selected text content.
+- Repository metadata persistence now records the exact latest commit and normalized snapshot required by Repository Analysis.
+- Project and Repository Analysis documentation now distinguish completed Update 01 acquisition from Update 02 detection/readiness work.
+- Current-state documents now identify the verified implementation branch and commit.
+
+### Verified
+
+- Implementation branch: `feature/github-repository-acquisition-analyzer-input-v1`.
+- Implementation commit: `cb796401afe8be64eb311a45e566fc315a13a00c`.
+- Base commit: `d2ad741c0ee48bf3eb3887a3357f6f450825c99a`.
+- Exact implementation scope: 19 files.
+- Ruff `0.15.20`: PASS.
+- Update 01 focused tests: 27 passed.
+- Full test suite: 609 passed.
+- Compileall: PASS.
+- Smoke test with database skipped: PASS.
+- Release gate with database skipped: PASS.
+- Remote feature-branch SHA verification: PASS.
+- Working tree after push: CLEAN.
+
+### Security and Architecture Boundaries
+
+- Raw GitHub installation access tokens are not persisted or returned.
+- Private source contents are not logged.
+- API routes do not call GitHub directly.
+- Repository Analysis does not call GitHub directly.
+- No database migration was added.
+- No Cloudflare operation or provider enablement was added.
+- `WORKER_PROVIDER_EXECUTION_MODE=disabled` remains unchanged.
+
+### Not Executed
+
+- Live GitHub API acquisition against a controlled installation.
+- Live PostgreSQL verification.
+- Live Redis worker execution.
+- Live Cloudflare API execution.
+- Real Cloudflare Pages deployment.
+- Merge, production redeploy, or branch-protection change.
+
 All notable YGIT MVP implementation releases and active engineering foundations are tracked here.
 
 ## Unreleased — Phase 0 Completion Record — 2026-07-24
@@ -408,3 +464,14 @@ Implemented Notification Engine with in-app notifications, unread count, mark-re
 - No new migration.
 - No new external dependency.
 - No real provider deployment execution in sandbox.
+
+## Update 1 — GitHub Repository Acquisition + Analyzer Input
+
+- Added ephemeral GitHub App installation credential acquisition through Connected Accounts public API.
+- Added authenticated GitHub repository metadata retrieval.
+- Added default-branch commit pinning and recursive Git tree acquisition.
+- Added fail-closed handling for truncated or oversized tree responses.
+- Added bounded UTF-8 acquisition for analysis-critical repository files.
+- Persisted normalized snapshots in existing Repository Engine JSON fields; no migration added.
+- Added commit-pinned analyzer input fields for tree SHA, snapshot completeness, and file contents.
+- Preserved Cloudflare provider execution disabled.

GITHUB_APP_INTEGRATION.md

@@ -1,7 +1,7 @@
 # YGIT GitHub App Integration Architecture
 
-Version: 1.1
-Status: Architecture Locked
+Version: 1.2
+Status: Architecture Locked; Update 01 Implementation Aligned
 Owner: Repository Integration
 
 ## Purpose
@@ -94,6 +94,41 @@ Cloudflare remains a separate OAuth-connected provider.
 
 GitHub App credentials must never be reused as Cloudflare credentials, and Cloudflare OAuth credentials must never be used for GitHub integration.
 
+## Update 01 Repository Acquisition Contract
+
+Update 01 implements repository reads through the connected GitHub App installation:
+
+```text
+Connected Account installation reference
+        ↓
+server-generated GitHub App JWT
+        ↓
+short-lived installation access token
+        ↓
+repository metadata
+        ↓
+default branch head commit
+        ↓
+exact commit tree
+        ↓
+complete recursive inventory
+        ↓
+bounded analysis-critical text files
+```
+
+The installation token is ephemeral. It is used only inside the Connected Accounts and GitHub Provider boundary for the current request. It must not be stored in `connected_accounts`, `repository_metadata`, analysis results, job payloads, logs, API responses, or documentation artifacts.
+
+The minimum repository-read permission target remains:
+
+```text
+metadata:read
+contents:read
+```
+
+A missing, disconnected, invalid, or expired installation credential fails closed. A truncated or oversized recursive tree is not accepted as complete analyzer evidence.
+
+Update 01 does not add GitHub write operations, webhook processing, GitHub OAuth, repository mutation, deployment execution, or Cloudflare credential reuse.
+
 ## Webhook Capability State
 
 The current YGIT MVP does not expose an approved GitHub webhook receiver endpoint and does not process GitHub webhook deliveries.
@@ -144,3 +179,22 @@ This contract does not:
 - change Cloudflare OAuth;
 - change AG-001;
 - create a YGIT App Engine.
+
+## Update 01 Evidence
+
+```text
+Implementation branch: feature/github-repository-acquisition-analyzer-input-v1
+Implementation commit: cb796401afe8be64eb311a45e566fc315a13a00c
+Focused tests: 27 passed
+Full suite: 609 passed
+Ruff 0.15.20: PASS
+Remote branch verification: PASS
+Live GitHub API verification: NOT EXECUTED
+```
+
+## Revision History
+
+| Date | Version | Summary |
+|---|---|---|
+| 2026-07-25 | 1.2 | Aligned the locked GitHub App architecture with Update 01 ephemeral installation-token repository acquisition |
+| Earlier | 1.1 | Locked GitHub App repository authorization, Keycloak user authentication, and default-disabled webhook capability |

GITHUB_APP_PERMISSION_CAPTURE_SPEC.md

@@ -1,7 +1,7 @@
 # YGIT GitHub App Installation Permission Capture Specification
 
-Version: 1.0
-Status: Approved for Implementation
+Version: 1.1
+Status: Implemented; Controlled Live Installation Verification Pending
 Owner: Connected Accounts / GitHub Provider
 
 ## Purpose
@@ -62,3 +62,32 @@ This patch does not:
 - create a database migration.
 
 A later independent UI patch will display the captured permission posture.
+
+## Update 01 Integration
+
+Repository Engine requests an ephemeral GitHub installation credential through the Connected Accounts public API. Connected Accounts validates that the stored GitHub account record is connected and that its installation reference can be resolved before issuing the short-lived credential.
+
+The captured scope metadata is safe account metadata; it is not itself an access token. Update 01 depends on the least-privilege target:
+
+```text
+metadata:read
+contents:read
+```
+
+The acquisition path fails closed when the GitHub account is missing, disconnected, invalid, expired, or cannot produce an installation credential.
+
+## Verification State
+
+```text
+Implementation commit: cb796401afe8be64eb311a45e566fc315a13a00c
+Local permission and acquisition contract tests: PASS
+Live installation permission verification: NOT EXECUTED
+GitHub App settings mutation: NOT PERFORMED
+```
+
+## Revision History
+
+| Date | Version | Summary |
+|---|---|---|
+| 2026-07-25 | 1.1 | Recorded Update 01 credential-acquisition dependency and live-verification boundary |
+| Earlier | 1.0 | Approved deterministic installation-permission capture contract |

PROJECT_ENGINE_DELIVERY_NOTE.md

@@ -22,3 +22,19 @@ Project Engine implementation added on top of YGIT Auth Engine v0.1.0.
 - Deployment History implementation
 
 Those remain separate implementation phases under Architecture Freeze v1.1.
+
+## Update 01 Integration Addendum
+
+Update 01 does not change Project Engine ownership. It documents and verifies the existing integration path in which project creation receives the Repository Engine record and initial Repository Analysis result through public boundaries.
+
+```text
+Project creation
+→ Repository Engine commit-pinned snapshot
+→ Repository Analysis quick result
+→ Project repository/analysis attachment
+→ deploy readiness remains gated by stored analysis evidence
+```
+
+Recalculation-time reattachment of a newer analysis remains Update 02 work. No Project Engine model, migration, route, or ownership boundary was added by Update 01.
+
+Verification reference: `cb796401afe8be64eb311a45e566fc315a13a00c`; full suite 609 passed.

PROJECT_STATUS.md

@@ -1,8 +1,8 @@
 # YGIT Project Status
 
 Version: 0.1.0
-Status: Active Engineering Snapshot
-Updated: 2026-07-24
+Status: Update 01 Implementation Verified; Draft PR Documentation Gate
+Updated: 2026-07-25
 Product: YGIT
 Company: Vib Tools
 
@@ -46,13 +46,15 @@ Business logic remains outside the Dashboard. Providers are not imported directl
 
 ## Engine Matrix
 
+Repository acquisition status: **commit-pinned snapshot implemented**.
+
 | Engine/component | Status | Important remaining work |
 |---|---|---|
 | Auth Engine | Implemented | Controlled production identity/session validation |
 | Connected Accounts Module | Implemented | Live account/credential lifecycle validation under production configuration |
 | Project Engine | Implemented | No critical foundation gap identified |
-| Repository Engine | Metadata persistence implemented; AG-002 standalone provider gate foundation added but not runtime-wired; live tree acquisition incomplete | GitHub App installation-token metadata/tree fetch, commit pinning, and private repository validation |
-| Repository Analysis Engine | Quick-analysis contract implemented; current live input is incomplete | Actual repository tree acquisition, deep-analysis execution, Project reattachment after recalculation, and broader framework validation |
+| Repository Engine | GitHub App installation-authenticated metadata, commit pinning, complete recursive tree snapshot, and analyzer-input handoff implemented; AG-002 standalone provider gate remains not runtime-wired | Controlled live private-repository validation and future provider-gate integration |
+| Repository Analysis Engine | Quick-analysis contract now receives a commit-pinned complete snapshot and bounded text evidence | Strong analyzer rules, deep-analysis execution, Project reattachment after recalculation, and Cloudflare readiness expansion |
 | Deploy Engine | Implemented; AG-001 provider gate foundation added but not runtime-wired | Provider result reconciliation and reviewed future gate integration |
 | Deploy Pipeline | Concrete Cloudflare orchestration and trusted policy-to-binding handoff implemented; default runtime disabled | Controlled live provider validation and operational hardening |
 | Deployment History Engine | Pipeline intent, provider-result, terminal-failure, and retry-safe replay persistence integrated | Controlled PostgreSQL validation and operational monitoring |
@@ -69,6 +71,15 @@ Business logic remains outside the Dashboard. Providers are not imported directl
 
 ## Recently Completed Foundations
 
+### Update 01 — GitHub Repository Acquisition + Analyzer Input
+
+- Connected Accounts resolves the stored GitHub App installation reference and creates a short-lived installation access token for approved Repository Engine calls.
+- GitHub Provider reads repository metadata through the installation token, resolves the default branch to commit `cb796401afe8be64eb311a45e566fc315a13a00c`-era implementation behavior, resolves the exact Git tree, and acquires a complete recursive inventory.
+- Repository snapshots are commit-pinned, versioned, bounded, and fail closed when GitHub reports a truncated or oversized tree.
+- Selected analysis-critical UTF-8 files are included within bounded content limits; sensitive filenames and unsupported/binary content are excluded.
+- Repository Analysis receives the complete snapshot through the Repository Engine public boundary and does not call GitHub directly.
+- No migration, Cloudflare execution, provider-mode change, UI-V2 change, or production deployment was included.
+
 - Worker database-aware dispatch contract.
 - Cloudflare credential acquisition boundary.
 - Connected Accounts avatar, status, connection date, scopes, last sync, and imported-repository reuse UI.
@@ -106,47 +117,35 @@ GitHub integration is architecture-locked to a GitHub App. Vib ID / Keycloak rem
 ## Latest Verification Evidence
 
 ```text
-Provider execution policy unit tests: 18 passed
-Provider policy runtime integration: 9 passed
-Deploy/redeploy handler binding regression: 5 passed
-Dispatcher DB regression: 5 passed
-Worker Runtime architecture: 4 passed
-Deploy/redeploy architecture: 2 passed
-AG-001 regression: 15 passed
-AG-002 regression: 9 passed
-Deployment History runtime: 8 passed
-Deployment History idempotency: 4 passed
-Live-readiness tooling: 18 passed
-Runtime image packaging: 4 passed
-GitHub App permission capture: 7 passed
-Dashboard compact provider cards: 10 passed
-Project Open UI: 9 passed
-Project Deploy UI: 9 passed
-Full suite: 579 passed, 1 warning
+Update 01 branch: feature/github-repository-acquisition-analyzer-input-v1
+Update 01 implementation commit: cb796401afe8be64eb311a45e566fc315a13a00c
+Update 01 base commit: d2ad741c0ee48bf3eb3887a3357f6f450825c99a
+Implementation file scope: 19
+Ruff 0.15.20: PASS
+Update 01 focused tests: 27 passed
+Full suite: 609 passed
+Previous foundation full suite: 579 passed, 1 warning
+Compileall: PASS
 Smoke --skip-db: PASS
 Release gate --skip-db: PASS
+Remote feature-branch SHA match: PASS
+Working tree after push: CLEAN
 Backend CI workflow: IMPLEMENTED
-Backend CI / Validate: SUCCESS
-Backend CI final-head pull-request run: 30096212556
-Backend CI final-head pull-request job: 89490793519
-Backend CI post-merge push run: 30106115262
-Backend CI post-merge push job: 89523839117
-Backend CI post-merge push verification: SUCCESS
-Phase 0 merge commit: 6e44866de9ec3a3a745777afc12276f903259709
-Phase 0 completion: COMPLETE
+Draft PR: PENDING DOCUMENTATION COMMIT
+Provider execution mode: DISABLED
 Branch protection required-check enablement: NOT AUTHORIZED
 ```
 
-Database checks were skipped. External providers were not executed.
+Database checks were skipped. Live GitHub, Cloudflare, PostgreSQL, Redis-worker, and production deployment behavior were not executed.
 
 ## Remaining Critical Path
 
-1. Redeploy the verified current `main` branch and validate the Dashboard compact provider cards, Project Open flow, and backend-readiness-gated Deploy flow.
-2. Reduce the GitHub App to the approved minimum permissions, reconnect the controlled installation, and verify captured permission scopes.
-3. Implement GitHub App installation-token repository acquisition with a pinned commit SHA and normalized real file-tree snapshot.
-4. Implement the approved deep-analysis execution and Project reattachment boundaries.
-5. Confirm `deploy_ready=true` from real repository evidence and execute one controlled Cloudflare Pages deployment.
-6. Resolve only defects demonstrated by live evidence.
+1. Commit and push the Update 01 documentation closure.
+2. Create the detailed Draft PR and require successful `Backend CI / Validate` on its final head.
+3. Complete exact-scope review and merge only after explicit authorization.
+4. Run controlled live GitHub App acquisition against an approved private repository after merge.
+5. Implement Update 02 strong analyzer and Cloudflare-readiness contracts using the acquired text evidence.
+6. Execute one controlled Cloudflare Pages deployment only after separate provider-execution authorization.
 7. Keep AG-001 and AG-002 runtime integration deferred until separate post-MVP architecture approval.
 
 ## Documentation Authority
@@ -164,6 +163,11 @@ Current-state documents:
 - `docs/ci/BACKEND_CI_SPECIFICATION.md`
 - `docs/ci/BACKEND_CI_IMPLEMENTATION_PLAN.md`
 - `docs/ci/BACKEND_CI_TESTING_AND_ROLLBACK_SPECIFICATION.md`
+- `docs/updates/README.md`
+- `docs/updates/UPDATE_01_GITHUB_REPOSITORY_ACQUISITION_COMPLETION.md`
+- `docs/updates/UPDATE_01_VERIFICATION_EVIDENCE.md`
+- `docs/updates/UPDATE_01_PR_CHECKLIST.md`
+- `docs/architecture/GITHUB_REPOSITORY_ACQUISITION_ANALYZER_INPUT_SPECIFICATION.md`
 - `.github/workflows/backend-ci.yml`
 
 Historical release artifacts retain their original versioned purpose. Where a historical artifact conflicts with this current snapshot, this document and the current source code take precedence for development status.
@@ -172,6 +176,7 @@ Historical release artifacts retain their original versioned purpose. Where a hi
 
 | Date | Revision | Summary |
 |---|---|---|
+| 2026-07-25 | 2.3 | Recorded Update 01 implementation commit `cb796401afe8be64eb311a45e566fc315a13a00c`, exact remote-branch verification, 609-test evidence, complete documentation set, and Draft PR gate |
 | 2026-07-24 | 2.2 | Recorded PR #1 controlled merge, merge commit `6e44866de9ec3a3a745777afc12276f903259709`, successful merged-main Backend CI, and Phase 0 completion |
 | 2026-07-24 | 2.1 | Recorded Backend CI implementation, successful Draft PR validation, security boundaries, and remaining post-merge Phase 0 gates |
 | 2026-07-23 | 2.0 | Locked the running baseline, reconciled current status/configuration evidence, and added the standalone AG-002 Repository Provider Gate foundation without runtime wiring |