docs: record slice 68 production branch trigger smoke

Author: rohans0509

docs/codealmanac-launch/decisions.md

@@ -166,6 +166,9 @@ Status: active.
   falls back to a `BranchSource` run.
 - Conversation-batch runs use the same per-branch delivery policy as branch
   runs. The old scheduler path must not hard-code commit delivery.
+- Branch-triggered cloud runs are immutable snapshots. The worker must
+  materialize the run's recorded `head_sha`, and when a range is needed it must
+  fetch the recorded `before_sha`; it must not run against the live branch tip.
 
 ## Naming
 

docs/codealmanac-launch/next-agent-brief.md

@@ -12,6 +12,24 @@ Cloud remains the primary product path. Local remains a free/dev surface with a
 parallel conceptual model where it is useful, but not a reason to muddy the
 cloud setup flow.
 
+## Current Verified State
+
+- Hosted repo branch `codex/workos-authkit-api-foundation` and hosted `main`
+  both include `eb8dba042c80ed573ad53399f002126d2e14bc29`.
+- Render service `srv-d8g8nb37uimc739vnnsg` is live on deploy
+  `dep-d93pp0eq1p3s73cuomp0`.
+- Modal app `codealmanac-hosted-updates` was redeployed after `eb8dba0`.
+- Chrome verified signed-in production `/setup` and the production repository
+  dashboard for `AlmanacCode/codealmanac`.
+- Fresh production branch push created run
+  `773da5fb-9871-4f83-8797-ddf651c635ce`; it delivered with summary
+  `No wiki changes made.`
+- Do not chase older failed smoke runs unless doing cleanup. The old failures
+  are historical evidence from stale worker images and pre-fix payloads.
+- The old conversation-batch run
+  `aeb55370-cbdd-4ded-af6a-5e0e22f0ef0a` still appears `running` from a stale
+  pre-fix Modal worker image.
+
 ## Last Completed Work
 
 Slice 50 added the browser-owned cloud setup entry:

docs/codealmanac-launch/progress.md

@@ -8,7 +8,7 @@ Percentages are planning estimates, not accounting metrics.
 
 ## Latest RelayForge Update
 
-Sent: 2026-07-03 after Slice 63 production setup pressure test.
+Sent: 2026-07-03 after Slice 68 production branch-trigger smoke.
 
 Route:
 
@@ -19,21 +19,21 @@ doppler run --project almanac --config dev -- \
   --binding rohan-almanac-main "..."
 ```
 
-Note: production Chrome verified setup, repository list, repository settings,
-reversible branch trigger/delivery save, and the CLI setup guide. Hosted
-frontend commit `47b1ada` is deployed to Vercel production at
-`codealmanac-hosted-gutvigm88-thealmanac.vercel.app` and aliased to
-`https://www.codealmanac.com`.
+Note: production Chrome verified setup and repository dashboard; Render is live
+on hosted commit `eb8dba0`; Modal `codealmanac-hosted-updates` is redeployed;
+a fresh GitHub branch push created run
+`773da5fb-9871-4f83-8797-ddf651c635ce`, which delivered with summary
+`No wiki changes made.`
 
 ## Percentages
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 96% | 96% | CodeAlmanac local/backend unchanged in Slice 63. |
-| CodeAlmanac CLI/public UX | 98% | 98% | PyPI `0.1.1` remains published and install-smoked; setup guide remains PyPI-shaped in production. |
-| CodeAlmanac-hosted backend/auth/API | 99% | 99% | Backend unchanged in Slice 63; production BFF trigger reads/writes succeeded through the frontend session. |
-| Hosted frontend/onboarding | 95% | 92% | Production Chrome verified setup, repository list, settings, live settings summary, reversible branch trigger save/restore, and CLI setup guide after Vercel deploy. |
-| Infra/deploy rename | 99% | 99% | Vercel production is live on `47b1ada`; Render remains live on `fdad34d`. |
+| CodeAlmanac backend/local | 96% | 96% | CodeAlmanac local/backend unchanged in Slice 68. |
+| CodeAlmanac CLI/public UX | 98% | 98% | Published CLI setup/capture were verified in earlier slices; Slice 68 used the CLI to disable the smoke trigger and revoke capture cleanup. |
+| CodeAlmanac-hosted backend/auth/API | 99% | 99% | Production branch push now creates an immutable branch-source run and worker completion delivered successfully. |
+| Hosted frontend/onboarding | 96% | 95% | Chrome verified signed-in `/setup` and repository dashboard after production fixes; dashboard showed delivered run. |
+| Infra/deploy rename | 99% | 99% | Render is live on `eb8dba0`; Modal app `codealmanac-hosted-updates` is redeployed; Vercel frontend unchanged. |
 
 ## Update Rule
 

docs/codealmanac-launch/verification-matrix.md

@@ -1292,3 +1292,43 @@ Current evidence:
   - Fresh published CLI setup through real Chrome approved `/cli-login`, stored
     auth in a temp HOME, and `whoami` returned `rohans0509` with cloud
     `https://api.codealmanac.com`.
+
+## Slice 68 Production Branch Trigger Smoke
+
+- Chrome verified signed-in production `/setup` for `rohans0509` and the
+  production repository dashboard for `AlmanacCode/codealmanac`.
+- Production GitHub App `push` webhook delivery is enabled.
+- Hosted commit `03c57f8` fixed branch pushes incorrectly mapping to first-wiki
+  initialization by introducing `InitialWikiSource` and mapping `BranchSource`
+  to CodeAlmanac ingest.
+- Hosted commit `eb8dba0` fixed branch-source worker checkout determinism:
+  branch-like runs now checkout the exact run `head_sha` and fetch
+  `before_sha` so `git:range:<before>..<head>` can be evaluated in the Modal
+  workspace.
+- Verification passed for `eb8dba0`:
+  - `uv run pytest tests/test_github_checkout_contract.py tests/test_modal_worker_contract.py -q`
+    (`23 passed`)
+  - `uv run pytest tests/test_architecture_contract.py tests/test_github_checkout_contract.py tests/test_modal_worker_contract.py tests/test_updates_contract.py tests/test_repositories_api_contract.py tests/test_cli_runs_api_contract.py -q`
+    (`165 passed`, `1` Starlette warning)
+  - `uv run ruff check src modal_app tests/test_github_checkout_contract.py tests/test_modal_worker_contract.py`
+  - real Git fetch-by-SHA smoke for the exact smoke `before_sha` and `head_sha`
+- Deploy and production smoke passed:
+  - Render deploy `dep-d93pp0eq1p3s73cuomp0` is live on hosted commit
+    `eb8dba042c80ed573ad53399f002126d2e14bc29`.
+  - Modal app `codealmanac-hosted-updates` was redeployed after the checkout
+    fix.
+  - Disposable branch push created run
+    `773da5fb-9871-4f83-8797-ddf651c635ce` with immutable source range
+    `d11d29b96dbfe334b2d9cb99fa5aafcc7893d98a..23a0a03209ff1804944eb094f589647dc13de47b`.
+  - The run delivered with summary `No wiki changes made.`
+  - Chrome refreshed the production dashboard and showed the delivered run at
+    the top.
+  - Cleanup completed: smoke trigger disabled, temp capture credential revoked,
+    remote smoke branch deleted, temp worktree removed.
+
+Known residue:
+
+- Older failed smoke runs remain visible and should be treated as historical
+  evidence.
+- Conversation-batch run `aeb55370-cbdd-4ded-af6a-5e0e22f0ef0a` is still
+  marked `running` from a stale pre-fix Modal image.

docs/codealmanac-launch/worklog.md

@@ -1894,3 +1894,31 @@
   `CLI login approved`, setup finished signed in as `rohans0509`, `whoami`
   returned cloud `https://api.codealmanac.com`, and `capture status
   --check-cloud --json` reached production with `signed_in: true`.
+- Slice 68 production branch-trigger smoke passed after two worker fixes.
+  Chrome verified signed-in `/setup` and the production repository dashboard
+  for `AlmanacCode/codealmanac`. GitHub App `push` delivery is enabled.
+- Slice 68 found the first worker bug through production: branch pushes were
+  being treated like first wiki initialization. Hosted commit `03c57f8`
+  introduced `InitialWikiSource` and mapped `BranchSource` to ingest.
+- Slice 68 found the second worker bug through production: branch-source
+  workers cloned the live branch at depth 1 instead of materializing the exact
+  run snapshot. Hosted commit `eb8dba0` makes branch-like runs checkout the
+  exact `head_sha` and fetch `before_sha` for `git:range`.
+- Verification for `eb8dba0` passed: hosted backend tests
+  `test_architecture_contract.py`, `test_github_checkout_contract.py`,
+  `test_modal_worker_contract.py`, `test_updates_contract.py`,
+  `test_repositories_api_contract.py`, and `test_cli_runs_api_contract.py`
+  (`165 passed`, `1` Starlette warning), hosted ruff, and a real Git
+  fetch-by-SHA smoke against the public CodeAlmanac repo.
+- Render deploy `dep-d93pp0eq1p3s73cuomp0` is live on hosted commit
+  `eb8dba0`. Modal app `codealmanac-hosted-updates` was redeployed from the
+  same checkout.
+- Fresh production push to disposable branch
+  `codealmanac-smoke/slice-68-20260703102325` created run
+  `773da5fb-9871-4f83-8797-ddf651c635ce` with
+  `before_sha=d11d29b96dbfe334b2d9cb99fa5aafcc7893d98a` and
+  `head_sha=23a0a03209ff1804944eb094f589647dc13de47b`. The run delivered with
+  summary `No wiki changes made.`
+- Chrome refreshed the production dashboard and showed the delivered run at the
+  top. Cleanup completed: smoke trigger disabled, temp capture credential
+  revoked, remote smoke branch deleted, temp worktree removed.

docs/plans/2026-07-03-github-webhook-contract-hardening.md

@@ -0,0 +1,245 @@
+# GitHub Webhook Contract Hardening Implementation Plan
+
+Status: planned research artifact. Use as the starting point before changing
+GitHub webhook intake again.
+
+**Goal:** Make hosted CodeAlmanac's GitHub webhook intake match GitHub's event schemas for the webhook families we depend on, without adding reconciliation or a parallel sync path.
+
+**Architecture:** Route webhook parsing by `X-GitHub-Event`, normalize supported payloads into typed Pydantic messages, and audit unsupported payloads as ignored. Control-plane messages carry the parent provider facts they need; fanout subscribers keep owning their own tables.
+
+**Tech Stack:** FastAPI, SQLModel, Pydantic, GitHub App webhooks, Octokit generated webhook schemas for research.
+
+---
+
+## Research Baseline
+
+Checked on 2026-07-03:
+
+- GitHub docs: `https://docs.github.com/en/webhooks/webhook-events-and-payloads`
+- GitHub Apps webhook docs: `https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps`
+- `@octokit/webhooks-schemas@7.6.1`: 66 top-level event families, 224 action variants.
+- `@octokit/webhooks-examples@7.6.1`: current dotcom examples for 58 event families.
+
+The current backend supports only these event families:
+
+```text
+installation
+installation_repositories
+repository
+push
+pull_request
+```
+
+That scope is correct for launch. The bug is not that we ignore most GitHub events; the bug is that the mapper currently guesses by payload shape instead of using `X-GitHub-Event`, and the `installation` action names do not match the schema.
+
+## Important Schema Findings
+
+`installation` actions are:
+
+```text
+created
+deleted
+new_permissions_accepted
+suspend
+unsuspend
+```
+
+Current code checks `suspended` and `unsuspended`, which is wrong.
+
+`installation_repositories` actions are:
+
+```text
+added
+removed
+```
+
+Each payload includes:
+
+```text
+installation
+repository_selection
+repositories_added
+repositories_removed
+requester
+sender
+```
+
+The `installation.account` object is present there, so the mapper can produce `AccountSnapshot` and `InstallationSnapshot` for delta events without calling GitHub again.
+
+Most repository-scoped events include these optional or required top-level objects:
+
+```text
+installation
+repository
+organization
+sender
+```
+
+That does not mean CodeAlmanac should persist every event. It means the webhook edge should route by event name, validate only supported families, and record unsupported families as ignored.
+
+## Out Of Scope
+
+- No login-time GitHub reconciler.
+- No background reconciler.
+- No broad "sync all installations" repair job.
+- No runtime dependency on Node or Octokit.
+- No modeling all 66 GitHub webhook families as Python messages.
+- No subscription expansion unless product work needs the event.
+
+## Target Shape
+
+```python
+message = github_webhooks.parse_github_message(event_name, payload)
+
+match event_name:
+    case "installation":
+        return parse_installation(payload)
+    case "installation_repositories":
+        return parse_installation_repositories(payload)
+    case "repository":
+        return parse_repository(payload)
+    case "push":
+        return parse_push(payload)
+    case "pull_request":
+        return parse_pull_request(payload)
+    case _:
+        return None
+```
+
+Supported control-plane messages carry parent snapshots:
+
+```python
+InstallationRepositoriesAdded(
+    account=AccountSnapshot(...),
+    installation=InstallationSnapshot(...),
+    repository_selection="selected",
+    repositories=[...],
+)
+```
+
+Identity fanout handles the parent rows:
+
+```python
+identity.on_installation_repositories_added(message):
+    accounts.upsert(message.account)
+    installations.upsert(message.installation)
+```
+
+Repository fanout handles repository scope only:
+
+```python
+repositories.on_installation_repositories_added(message):
+    repository_scope.sync_installation(message.installation.installation_id)
+```
+
+## Implementation Tasks
+
+### Task 1: Route Parsing By GitHub Event Header
+
+**Files:**
+
+- Modify: `backend/src/almanac/services/github/service.py`
+- Modify: `backend/src/almanac/services/github/webhooks.py`
+- Test: `backend/tests/test_github_service_contract.py`
+
+Steps:
+
+1. Change `GitHubService.handle_webhook` to call `parse_github_message(event, payload)`.
+2. Replace shape-sniffing in `map_payload(payload)` with event-name dispatch.
+3. Keep unsupported event families returning `None`.
+4. Add tests showing unsupported `check_run` / `check_suite` remain ignored.
+5. Add a regression test showing a payload with both `repository` and `installation` is routed by event name, not shape.
+
+### Task 2: Correct Installation Action Contract
+
+**Files:**
+
+- Modify: `backend/src/almanac/services/github/webhooks.py`
+- Modify: `backend/src/almanac/services/github/webhook_messages.py`
+- Test: `backend/tests/test_github_service_contract.py`
+
+Steps:
+
+1. Accept `suspend` and `unsuspend`.
+2. Stop accepting non-schema `suspended` and `unsuspended`.
+3. Map `suspend` to `InstallationSuspended`.
+4. Map `unsuspend` to `InstallationUnsuspended`.
+5. Ignore `new_permissions_accepted` unless product behavior requires it later.
+
+### Task 3: Carry Parent Snapshots On Installation Repository Deltas
+
+**Files:**
+
+- Modify: `backend/src/almanac/messages/github.py`
+- Modify: `backend/src/almanac/services/github/webhook_messages.py`
+- Modify: `backend/src/almanac/wiring/fanout/identity.py`
+- Test: `backend/tests/test_installations_contract.py`
+- Test: `backend/tests/test_github_service_contract.py`
+
+Steps:
+
+1. Add `account: AccountSnapshot` and `installation: InstallationSnapshot` to `InstallationRepositoriesAdded`.
+2. Add the same fields to `InstallationRepositoriesRemoved`.
+3. Populate those snapshots from `installation.account` and `installation.id`.
+4. Subscribe identity fanout to both delta message types.
+5. Upsert account and installation in identity fanout before repository fanout syncs repositories.
+6. Keep repository fanout focused on `RepositoryScope`.
+
+### Task 4: Add Schema Guardrails For Supported Families
+
+**Files:**
+
+- Modify: `backend/tests/test_github_service_contract.py`
+- Optional create: `backend/tests/fixtures/github_webhooks/README.md`
+
+Steps:
+
+1. Add compact fixture payloads for the five supported event families.
+2. Include action coverage for:
+   - `installation.created`
+   - `installation.deleted`
+   - `installation.suspend`
+   - `installation.unsuspend`
+   - `installation_repositories.added`
+   - `installation_repositories.removed`
+   - `repository.renamed`
+   - `repository.transferred`
+   - `repository.deleted`
+   - `push`
+   - supported `pull_request` actions
+3. Assert ignored actions are audited as ignored, not invalid.
+4. Assert malformed supported payloads are audited as invalid.
+
+### Task 5: Update Launch Docs
+
+**Files:**
+
+- Modify: `docs/codealmanac-launch/worklog.md`
+- Modify: `docs/codealmanac-launch/progress.md`
+- Modify: `docs/codealmanac-launch/verification-matrix.md`
+- Modify: `docs/codealmanac-launch/next-agent-brief.md`
+- Optional modify: `docs/codealmanac-launch/auth-api-contract.md`
+
+Steps:
+
+1. Record the schema inventory result.
+2. Record that reconciliation remains out of scope.
+3. Record that webhook parsing is event-header routed.
+4. Update percentages only after tests and deployment.
+
+## Verification
+
+Run in hosted repo:
+
+```bash
+cd /Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence
+uv run pytest backend/tests/test_github_service_contract.py backend/tests/test_installations_contract.py -q
+uv run pytest backend/tests/test_repositories_contract.py backend/tests/test_wiki_contract.py -q
+uv run ruff check backend/src backend/tests
+```
+
+If backend changes pass, deploy hosted backend/frontend together only after the coherent slice is complete.
+
+## Decision Check
+
+This plan fixes real contract drift and the DB-wipe webhook edge without making DB wipe a supported product workflow. If we later want first-class repair, that should be a separate reconciler design with explicit product semantics.