docs(07-05): complete the debt-closure + known-limitations plan — SUMMARY
- IN-01/IN-02/IN-03 paid (dead export gone, wrangler comment truthful, exact-900 s boundary pinned green) - docs/KNOWN-LIMITATIONS.md shipped (D-08) + /help pointer line en+ms (CS5 green) - /cari re-arm recorded honestly (all scopes armed) + A1/A3 closure - suite 126/126; STATE.md/ROADMAP.md untouched (orchestrator-owned)
This commit is contained in:
araharah-executor
@@ -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*
|
||||
Reference in New Issue
Block a user