فادي مندي
Health Debug
الصفحات · Health Debug

Session Card — M0 Foundation

Per-module session list for M0 Foundation. Implements the framework in docs/plan/13-execution-modules-and-sessions.md (§2 sub-module split, §5 done-criteria templates, §6 brain handoff). Open this card at the start of any M0 session, together with the brain (memory_recall the build-ledger and the latest session-handoff for the cell).

Purpose

M0 is the core: everything the eight protocol engines and every client stand on, and nothing engine-specific. It is deliberately split into eight session-sized sub-modules (M0.1–M0.8) so each ends cleanly with a handoff. The backend half (M0.1–M0.4) boots the ToGO microkernel, wires auth, stands up the engine plugin framework, and proves the expand-contract migration harness — establishing CI where the legacy repo had none. The web half (M0.5–M0.7) delivers the app shell, the single-source theme engine, and the ICU/RTL i18n engine. M0.8 is the MCP server + CLI skeleton, which trails M1 backend because its first real tool needs /today to exist. No protocol/engine logic is built in M0: the reference plugin (M0.3) is a skeleton with no engine logic, and the framework must be able to represent engine state without ever computing it. Gate: M0.1–M0.4 must land before any engine backend session; M0.5–M0.7 before any web/desktop client engine session.

Parameters & invariants relevant to M0

M0 builds no engine, so it introduces no engine numbers of its own. Instead it establishes the scaffolding that must faithfully carry the exact spec constants later, and enforce them by CI.

  • Schema rule (every backend session): every PostgreSQL column is NOT NULL with a defined default; migrations are strictly expand-contract; tooling is sqlc + Atlas. M0.1 wires the CI lint gate that fails any column lacking NOT-NULL+default; M0.4 proves the harness.
  • Auth model (TOGO auth): personal access tokens (PATs) for native / mcp / desktop / extension; session cookie for web. Deny-by-default request guard + explicit allowlist. App users row keyed to the auth identity. Cross-user isolation returns 404, not 403 (never leak resource existence).
  • Injected clock: no time.Now() inside any core/ package; all temporal logic reads an injected clock so tests can drive a fake clock. M0.3 establishes this; the engines depend on it for cooldowns/windows.
  • i18n: ICU Message Format, en + ar catalogs, dir=rtl root, CSS logical properties, mirrored progress bars, no string concatenation. M0.7 adds the i18n coverage CI gate.
  • Color spec (exact — M0.6 tokens carry these verbatim):
    • Dark: #1A1A1A bg / #00FF33 neon-green glow timers / #00CCFF cyan buttons / #FF3333 red alerts (glow effects).
    • Light: #FFFFFF bg / #20A060 teal / #0070A0 deep cyan (flat).
  • Engine constants that must NEVER appear in M0 framework or client code (they live only in each engine's core/ later; listed here so the thin-client / SSOT audits know what to grep for): Hydration 250ml unit, 5000ml/day cap, 30-second cooldown; Caffeine Block first-90-minutes post-wakeup; GERD 4-hour pre-sleep window (water / chamomile / anise only); Medication Grace 60-minute window; Cycle 3 consecutive logged cycles before predicting; Pomodoro 25/5/15, long break every 4 cycles, target 8 (PENDING ratification — not spec-fixed). M0.3's reference plugin skeleton must contain none of these.

Session table

Session IDs follow S-<date>-<Mx>-<surface>-NN; leave <date> and NN as placeholders until the session actually runs (e.g. S-2026-09-05-M0.1-backend-01).

Session IDSurfaceScopeEntry depsDone criteria (per doc 13 §5)Plan docs to read
S-<date>-M0.1-backend-NNbackendToGO microkernel project boots; config loading; /healthz; Docker compose bringing up the ToGO postgres image; Atlas + sqlc wired; the NOT-NULL+default schema-lint CI gate; CI skeleton (legacy had none).—Foundation: docker compose up → /healthz returns 200 end-to-end, covered by CI; the schema-lint gate is in place and fails red on a seeded column missing NOT-NULL or default; CI skeleton runs green on main.13; 04 §1 (structure), §3 (sqlc+Atlas), §4 (NOT-NULL rule), §5 (expand-contract); 00 master plan
S-<date>-M0.2-backend-NNbackendTOGO auth plugin integrated; deny-by-default request guard + allowlist; app users row keyed to auth identity; personal access token issue/verify; cross-user isolation test.M0.1Foundation: login/PAT auth works end-to-end; a test proves an un-allowlisted route is blocked by default; cross-user isolation test passes returning 404-not-403 and runs in CI; every new column NOT-NULL+default via expand-contract migration.13; 04 §2 (auth), §6.1 (users/auth schema), §7 (REST conventions); 10 (security)
S-<date>-M0.3-backend-NNbackendEngine plugin framework: plugin contract on the Microkernel registry, hook bus, injected clock, the pure-core/ pattern, and one reference plugin skeleton with no engine logic.M0.1Foundation: the reference plugin registers on kernel boot and the hook bus dispatches to it (test-covered with a fake clock); a test asserts the skeleton exposes no protocol constant (grep-clean); the core/ pattern is documented for engines to copy.13; 04 §8 (one-plugin-per-engine layout), §9 (testing); 03 §0 (global rules / SSOT), §9 (cross-engine architecture)
S-<date>-M0.4-backend-NNbackendExpand-contract migration harness proven end-to-end with one real migration; standard error envelope + ICU-localized rejection codes.M0.1Foundation: one migration runs expand→backfill→contract against real Postgres in CI (replayable/idempotent); resulting columns all NOT-NULL+default (schema-lint green); a rejected request returns the error envelope with an ICU-localized rejection code (en+ar), test-covered.13; 04 §4 (NOT-NULL rule), §5 (expand-contract playbook), §7 (REST/error conventions); 01 (i18n rejection codes)
S-<date>-M0.5-web-NNwebReact + TanStack app shell; router skeleton; typed API client; auth/login flow against M0.2 (web = session cookie).M0.2Foundation/Client: app builds and the router renders; the typed client calls the backend; login authenticates against M0.2 and lands an authed route; covered by a test or documented manual check; thin-client/SSOT audit passes (no protocol/timer logic in the shell).13; 05 §2 (structure), §3 (routing & server state); 04 §2 (auth), §7 (REST)
S-<date>-M0.6-web-NNwebTheme engine: dark-glow / light-flat semantic tokens; system-preference + manual override; no-flash first paint; single token source.M0.5Foundation: both modes render per the strict color spec (exact hex above); system + manual override both work; no flash on first paint (documented check); a CI guard/test enforces exactly one token source (legacy liability was three hand-maintained token files).13; 05 §4 (theming engine); 01 (color spec / core opinions); 12 (legacy design-system SSOT map)
S-<date>-M0.7-web-NNwebi18n engine: ICU Message Format; en/ar catalogs; dir=rtl root; CSS logical properties; mirrored progress bars.M0.5Foundation: en and ar catalogs load; ICU formatting used (no concatenation); dir=rtl root flips layout and progress bars mirror; an i18n coverage CI gate fails the build on any missing ar key (legacy i18n coverage trap).13; 05 §5 (i18n), §5b (RTL strategy); 01 (i18n rules); 12 (legacy i18n coverage trap)
S-<date>-M0.8-mcp-NNmcpMCP server + CLI skeleton: PAT auth, transport, first tool wired once /today exists. Trails M1 backend.M0.2, M1 backendMCP: server + CLI boot; PAT auth works; transport connects; the first tool calls the real API and returns server state verbatim; holds no protocol logic and no AI keys; excluded tools (no complete_break) stay excluded.13; 11 (MCP integration plan); 04 §2 (PAT auth), §7 (REST); 03 §1 (Hydration → /today)

Ordering within M0: M0.1 first (everything hangs off CI + compose). M0.2, M0.3, M0.4 each depend only on M0.1 and may proceed in any order (or in parallel across agents, tracked by the build ledger). M0.5 needs M0.2 (login); M0.6 and M0.7 need M0.5. M0.8 is sequenced after M1 backend despite living in this card, because its first tool needs /today.

Notes & gotchas

  • CI is new ground. The legacy repo had no CI at all. M0.1 stands up the pipeline; every later gate (schema-lint, thin-client/SSOT audit, i18n coverage, single-token-source) attaches to it. Treat the pipeline itself as a first-class deliverable, not an afterthought.
  • Single token source (M0.6). The legacy liability was three hand-maintained token files that drifted (see legacy design-system SSOT memory 07866eb5, doc 12). Enforce one source of truth with a CI guard so a second token file cannot be introduced.
  • i18n coverage trap (M0.7). Legacy shipped untranslated keys silently (memories ecfdb60e, 911186c7). The coverage gate must fail the build on any missing ar key, and no string may be built by concatenation — ICU only.
  • 404-not-403 (M0.2). Cross-user access must return 404, never 403, so the API never confirms a foreign resource exists (legacy auth/isolation invariants). Bake this into the isolation test.
  • Deny-by-default + allowlist (M0.2). New routes are blocked until explicitly allowlisted; a test should prove a fresh route is denied before it is listed.
  • Injected clock (M0.3). No time.Now() in core/ — ever. Every engine's temporal logic (cooldowns, windows, grace) will depend on the fake-clock capability established here.
  • Auth split. Web uses the session cookie; native / mcp / desktop / extension use PATs. Keep the M0.5 web flow cookie-based and the M0.8 mcp flow PAT-based.
  • Reference plugin carries no engine logic (M0.3). The skeleton proves registration + hook bus
    • clock injection only. Do not sneak any of the engine constants (hydration 250ml/5000ml/30s, GERD 4h window, etc.) into it — the grep audit will (and should) catch them.
  • M0.8 timing. Do not attempt M0.8 before M1 backend lands /today; a skeleton with no real endpoint to call cannot satisfy the MCP done template (calls the real API, returns state verbatim).
  • PENDING DESIGN. The web "Human Node" geometric status diagram (doc 05 §6) is design-dependent and out of M0 shell scope — M0.5 stubs the route only. The exact glow-rendering technique for the neon-green timer tokens beyond the fixed hex values is not pixel-specified — flag as PENDING DESIGN and keep the token layer swappable. Pomodoro 25/5/15 intervals remain PENDING ratification but are irrelevant to M0.

Handoff reminder

At session end, follow doc 13 §6: write one session-handoff memory to the healthdebug brain — retain the content, then memory/edit to attach metadata — with a unique source_ref: handoff/M0-foundation/<surface>/<n> and metadata: {project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"M0", title:"Handoff <session-id>", next:"<module+surface>", tags:[...]}. Then update the single build-ledger memory (source_ref: build-ledger, edited in place) so one recall shows the whole frontier and the recommended next session. Any architectural decision or new open question also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc.