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 .gitignored — 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	TBD	TBD