diff --git a/.planning/phases/07-hardening-private-launch/07-05-SUMMARY.md b/.planning/phases/07-hardening-private-launch/07-05-SUMMARY.md new file mode 100644 index 0000000..a12e515 --- /dev/null +++ b/.planning/phases/07-hardening-private-launch/07-05-SUMMARY.md @@ -0,0 +1,130 @@ +--- +phase: 07-hardening-private-launch +plan: 05 +subsystem: docs-security +tags: [initdata-hmac, kv-ttl, telegram-setmycommands, known-limitations, debt-closure, i18n] + +# Dependency graph +requires: + - phase: 02-bot-skeleton-initdata-security + provides: the initData HMAC validator (D-13/D-14), the KV session layer, the 3 INFO findings (IN-01/02/03) + - phase: 03-mini-app-shell-geolocation + provides: the device-matrix A1/A3 assumption notes and the honesty protocol + - phase: 06-turn-by-turn-guidance-live-driving + provides: the c3 cross-metro CPU measurement evidence (measure-route-cpu.mjs LADDER HISTORY) +provides: + - the exact-900 s initData freshness boundary pinned by a named test vector (T-07-08) — a `>=` regression cannot ship + - the IN-01 cleanup — dead ParsedInitData export deleted, three read-helper Intent comments + - the IN-02 present-tense wrangler.jsonc namespace record (T-07-23) + - docs/KNOWN-LIMITATIONS.md — the driver+fork known-limitations document (D-08) + - the /help limitations pointer line in both locales (strings-module single copy, CS5-invisible) + - the /cari re-arm record (all scopes armed 2026-10-25) and the A1/A3 assumption closure +affects: [07-06 launch gate (checks the doc + /help accuracy), forks (audit onboarding), 07-04 budget record] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Intent comments on non-obvious security catch blocks (malformed-vs-tampered precedence stated at the code site)" + - "Boundary-pin test vectors: the middle point of a comparator boundary gets its own named case" + - "Single-copy URL law: a doc pointer URL lives exactly once per locale, in the strings module" + +key-files: + created: + - docs/KNOWN-LIMITATIONS.md + modified: + - bot/src/security/initdata.ts + - bot/test/initdata.test.mjs + - bot/wrangler.jsonc + - bot/src/i18n/strings.ts + - .planning/phases/03-mini-app-shell-geolocation/03-DEVICE-MATRIX.md + +key-decisions: + - "The /help pointer URL is the repo's ACTUAL remote (http://gitmirah:3000/c-fu/arah2/src/branch/main/docs/KNOWN-LIMITATIONS.md), not the plan's default github.com/araharah/araharah — the origin is a Gitea instance serving HTTP only (TLS probe failed; HTTPS link would be dead); the URL resolves once the launch checklist's 'repo pushed' step lands main on the remote" + - "The battery paragraph states the METHOD and points at the launch-gate record instead of claiming a completed measurement — the battery run happens in 07-06 (wave 3), after this doc ships; the no-fake protocol outranks the plan's 'was MEASURED' phrasing" + +patterns-established: + - "Boundary-pin vector naming: 'T4 freshness boundary: age 900 s → ok:true (the boundary is INCLUSIVE)' — the case name states the claim it pins" + - "Dated debt-closure sections appended to historical device-gate files — history never rewritten" + +requirements-completed: [PX-04] + +# Metrics +duration: 12min +completed: 2026-10-25 +--- + +# Phase 7 Plan 05: Debt Closure + Known Limitations Summary + +**The three Phase-2 INFO debts paid (dead export deleted, wrangler comment truthful, the 900 s freshness boundary pinned by a green vector), plus the shipped known-limitations document with a /help pointer line in both locales and the honest /cari re-arm + A1/A3 closure records.** + +## Performance + +- **Duration:** 12 min +- **Started:** 2026-10-24T20:43:27Z +- **Completed:** 2026-10-25T04:52:00Z (+08) +- **Tasks:** 3/3 +- **Files modified:** 6 + +## Accomplishments + +- **IN-03 (security pin, T-07-08):** the exact-900 s initData freshness edge now has its own named vector — `T4 freshness boundary: age 900 s → ok:true (the boundary is INCLUSIVE)` — so a `>` → `>=` comparator regression turns red. The comparator itself is untouched (it was already correct; the test makes the claim a pin). Suite: 126/126. +- **IN-01:** the never-constructed `ParsedInitData` export is deleted (verified sole-repo hit was its own declaration); the three read-helper catch blocks now carry `Intent:` comments stating the malformed-vs-tampered precedence (D-14) and the chat-degrade law. +- **IN-02 (T-07-23):** `bot/wrangler.jsonc` line 2 states the post-fact truth — the chat_sessions namespace id below is live, no re-creation. +- **D-08:** `docs/KNOWN-LIMITATIONS.md` ships with all seven sections — OSM data gaps, the c3 cross-metro CPU degradation with its measurement evidence (2–8 ms short routes vs p95 38–93 ms cross-metro, Workers Paid rejected on the $0 mandate), the /cari menu defect with the type-the-command workaround (T-07-24), the beta-quality statement, the roadmap pointers (WASM-router / ALT / engine B — none in this release), the privacy paragraph, and the fork-facing audit commands. +- **/help pointer line (en + ms):** one line appended to each `helpMenu`, NOT `/`-prefixed so the CS5 command-menu parse ignores it (CS5 green — suite 126/126); URL identical in both locales, exactly one copy per locale (D-05 law). +- **/cari re-arm (T-07-26):** `npm run bot:commands` ran 2026-10-25 — all six scopes `ok:true`, literal line `all command scopes armed` recorded; residual Telegram client-caching risk stated. +- **A1/A3 closure:** A1 NOT RETIRED as a mechanism hypothesis (mitigated-by-design via `web/src/location/chain.ts` polling degradation); A3 RETIRED as a decision constraint (remote workers.dev origin). The Phase-3 FINAL VERDICT table untouched. + +## task Commits + +Each task was committed atomically: + +1. **task 1: pay IN-01 and IN-02 (dead code + the stale wrangler comment) and pin IN-03 (the exact-900s boundary)** - `84cb93d` (fix) +2. **task 2: the known-limitations document (D-08) + the /help pointer line (en + ms)** - `78482ab` (feat) +3. **task 3: the /cari re-arm attempt + the A1/A3 assumption closure, recorded honestly** - `6e0673f` (docs) + +## Files Created/Modified + +- `docs/KNOWN-LIMITATIONS.md` — NEW: the driver+fork limitations document (D-08), clinical-prose style per `docs/CONFIGURATION.md` +- `bot/src/security/initdata.ts` — dead `ParsedInitData` export deleted; three `Intent:` comments on the read-helper catch blocks +- `bot/test/initdata.test.mjs` — the exact-900 s boundary vector (IN-03) +- `bot/wrangler.jsonc` — the stale plan-scoped comment replaced with the present-tense live-id record (IN-02) +- `bot/src/i18n/strings.ts` — the `Known limits:` / `Had panduan:` pointer line in both helpMenu strings +- `.planning/phases/03-mini-app-shell-geolocation/03-DEVICE-MATRIX.md` — the dated `## 2026-10-25 — Phase 7 debt closure (/cari re-arm + A1/A3)` section (force-added; .planning is gitignored) + +## Decisions Made + +- **Pointer URL = the actual repo remote.** The plan's default `github.com/araharah/araharah` is not this repo; `git remote -v` gives `http://gitmirah:3000/c-fu/arah2.git` (a Gitea instance). HTTPS probe to the same host failed (no TLS), so the plan's "use the HTTPS remote" fallback resolves to the HTTP origin with the browser-view path (`/src/branch/main/docs/KNOWN-LIMITATIONS.md`, `.git` stripped) — verified valid Gitea path format; it 404s today only because the remote branch is behind local main, and the D-09 launch checklist's "repo pushed public" step resolves it before any driver sees /help. +- **Battery wording honesty.** The plan's §Beta-quality draft says battery "was MEASURED"; the measurement actually happens in the 07-06 launch-gate session (wave 3), after this doc ships. The shipped paragraph states the method (≥30 screen-on minutes, battery % read at start/end) and points at the launch-gate file as the record holder, with the run signed before the first driver is onboarded — the no-fake protocol (D-05/07's honesty law) outranks the plan's tense. +- **`budget-audit` named before it exists.** §How-to-run names `npm run budget-audit` per the plan; the script ships in plan 07-04 (wave 2, currently not yet executed). By launch time both audit commands exist; noted here so the launch gate verifies it. + +## Deviations from Plan + +None — plan executed exactly as written (the two decisions above are the plan's own prescribed fallbacks: use the actual remote URL, record the choice; and the honesty-law tense adjustment is documented rather than a fabricated claim). + +## Issues Encountered + +- The Gitea remote had no TLS endpoint (HTTPS probe returned connection failure) — resolved by using the HTTP origin, matching the URL form every existing doc (`README.md`, `docs/DEVELOPMENT.md`, `docs/TESTING.md`) already cites for `git clone`. +- The plan's device-matrix criterion `grep -c "FINAL VERDICT" == 1` initially returned 2 because the new closure section referenced the historical table by that name — reworded to "historical verdict table" and the commit amended (`6e0673f`). + +## User Setup Required + +None - no external service configuration required. (The /cari re-arm consumed the existing gitignored `bot/.dev.vars` token; no new secrets introduced.) + +## Next Phase Readiness + +- The D-09 launch checklist's "known-limitations shipped · /help accurate" items are satisfiable now; plan 07-06's gate verifies the doc + pointer line. +- `npm run budget-audit` (named in the doc's fork-audit section) ships in plan 07-04 — the launch gate should confirm it exists before signing. +- The battery record (07-LAUNCH-GATE.md) lands in 07-06; the doc's battery paragraph points at it. + +## Self-Check: PASSED + +- All 6 created/modified files exist on disk (verified 2026-10-24T20:47Z). +- All 3 task commits exist in git log (`84cb93d`, `78482ab`, `6e0673f`). +- Final verification: `npm test -w bot` → 126 passed, 0 failed; `npm run bot:typecheck` → clean. +- `.planning/STATE.md` and `.planning/ROADMAP.md` untouched by this plan's commits (orchestrator-owned). + +--- +*Phase: 07-hardening-private-launch* +*Completed: 2026-10-25*