Closer/Engineering_Reference_Manual_Plan.md

# Engineering Reference Manual Review Plan — Phase 4 (2026-07-11)

**Status: 🟡 IN PROGRESS** — covering 17 commits since Phase 3 completed (`c5ead4cb`).

Triggered by `_null` after Phase 3 completion to catch manual drift from the
last 17 commits on `dev`. Phase 3 was a full evidence-first sweep; Phase 4 is a
targeted re-review scoped to commits that materially changed code the manual
references (billing, repo layout, dead-file cleanup, FCM QA tooling, copy
catalog start).

## Approach

- **6 batches**, scoped to a category of changes from the last 17 commits.
- **Evidence-first.** For every claim in the manual, re-verify against the
  live source.
- **One commit per batch** per the standing git discipline (one batch = one
  commit = one push). Each commit must be pushed before the next batch starts.
- **No commits for batches with no findings** — log a no-op to this file only.

## Batches

### Batch 1 — Repository layout: dead-file sweep (21392ec2) + server/ removal (42fba641)
- Verify `## Repository layout` (Android + iOS + Cloud Functions + Shared) doesn't
  reference removed files (e.g. `NotificationHelper.kt`, `NotificationPermissionHelper.kt`,
  `FakeQuestionRepository.kt`, `QuestionJsonParser.kt`, `Entitlement.kt`).
- Verify no references to the removed `server/` Express backend (was Tier 3
  cleanup, kept the dist that the actual Cloud Functions use).
- 4103c433 already dropped "dead references" — confirm nothing was missed.
- Commit if any manual updates needed.

### Batch 2 — Billing: RevenueCat SDK 10.12.0 → 10.13.0 (8cb23ea2) + webhook HMAC-SHA256 fix (89d06eeb) + secret key gitignore (48217dd7)
- Verify `## Billing` (RevenueCat integration + Webhook + Premium-gated features):
  - SDK version now 10.13.0 (was 10.12.0, was 8.20.0 pre-Phase 3).
  - Webhook auth: actual auth scheme is HMAC-SHA256, not the prior scheme.
  - `revenucat_secret_api.md` is now `.gitignore`d — does the manual's
    "Files that must never be committed" section need this added?
- Commit if any manual updates needed.

### Batch 3 — Cloud Functions: webhook handler source-of-truth update (89d06eeb)
- Verify the Cloud Functions section's description of `revenueCatWebhook`
  matches the new auth scheme (HMAC-SHA256 signature verification).
- Verify any other Cloud Functions section claims that the webhook handler
  is the only billing touch-point (Tier 3 server/ removal is a reminder).
- Commit if any manual updates needed.

### Batch 4 — Engineering conventions: copy catalog start (51efff3f, 23cd2139, 2c3c2df8) + string resource cleanup (59e03369)
- Verify `### Naming` / `### Error handling` / any UI convention sections
  reflect the new `CloserCopy` catalog pattern.
- Verify no references to the 55 purged string resources.
- Verify no references to removed `core/analytics`, `core/billing`,
  `core/navigation`, `core/notifications` packages or their submodules.
- Commit if any manual updates needed.

### Batch 5 — Notifications / FCM: qa_push.js token-selection fix (c60fa958)
- Verify `## Notifications` (FCM + TokenRegistrar) doesn't claim a different
  token-selection strategy than the live code.
- Manual may or may not reference the QA script — check `qa/qa_push.js`.
- Commit if any manual updates needed.

### Batch 6 — Final pass: TOC + anchor integrity
- Re-run anchor/TOC verification.
- One final commit if any cleanup needed.

## Phase 4 results

| Batch | Section | Issues found | Commit |
|---|---|---|---|
| 1 | Repository layout: dead-file sweep + server/ removal | None — 4103c433 already covered all the dead-file references; the `core/notifications/`, `core/navigation/`, `core/analytics/`, `core/billing/` directories still exist and hold live code (TokenRegistrar, AppMessagingService, AppNavigation, etc.) so the line-963 and line-1021 references are still accurate. No stale `server/` references remain. | (no-op) |
| 2 | Billing: RevenueCat SDK + webhook + secret key | (1) Cloud Functions tree (line 203) still said "Ed25519 signature verify (NOT exported / not deployed)" — fixed to "HMAC-SHA256 signature verify (exported, deploy gated on REVENUECAT_WEBHOOK_SECRET)". (2) `purchases:10.12.0` on Android (line 869) → `purchases:10.13.0`. (3) `RevenueCat 10.12.0` in Gradle dep list (line 1134) → `RevenueCat 10.13.0`. (4) `revenucat_secret_api.md` added to the "Files that must never be committed" representative list (it was added to .gitignore in 48217dd7 but the manual didn't list it). | (this commit) |
| 3 | Cloud Functions: webhook handler | Line 831 (per-module responsibilities) said "RevenueCat webhook (source-only; not exported/deployed)" — fixed to "exported; deploy gated on `REVENUECAT_WEBHOOK_SECRET`". All other webhook-related lines (843-844, 905-908, 910) were already updated by 89d06eeb itself. | (this commit) |
| 4 | Engineering conventions: copy catalog + string resource cleanup | None — the manual already references `docs/copy-guide.md` (line 1063) as the source of voice; the new `CloserCopy` Kotlin catalog is internal implementation tracked in `docs/CopyMigration.md` and doesn't change the voice contract. The 55 purged string resources were already off-grid (no manual references to `strings.xml`). | (no-op) |
| 5 | Notifications / FCM: qa_push.js | None — the manual documents the production FCM token pipeline (TokenRegistrar → onAnswerWritten → fcmTokens subcollection fan-out, line 963+) but does not reference the `qa/qa_push.js` helper script. The c60fa958 fix only changes how the QA helper picks a token (newest instead of `docs[0]`); the production path is unchanged. | (no-op) |
| 6 | TOC + anchor integrity | 1 broken anchor: `### iOS → Android sealed-answer bridge (...)` had a `→` in the heading text; the auto-generated slug was `ios--android-sealed-answer-bridge-wrapreleasekeycallable` (double dash) but the TOC + the in-text link both pointed to `ios-android-sealed-answer-bridge-wrapreleasekeycallable` (single dash). Fixed by adding an explicit `{#ios-android-sealed-answer-bridge-wrapreleasekeycallable}` anchor. Re-run: 62/62 TOC + 62/62 in-text anchors resolve. | (this commit) |