chore: add plan and phase reports for D1 + cron rollout

plans/260415-1010-d1-cron-infra/phase-05-jsdoc-pass.md

@@ -0,0 +1,104 @@
+# Phase 05 — JSDoc Pass
+
+**Priority:** P2 (can run in parallel with 01–04)
+**Status:** Complete
+
+## Overview
+
+Add ESLint + `eslint-plugin-jsdoc` for JSDoc syntax/completeness linting. Add `@typedef` definitions and annotate public functions. No `tsc`, no `jsconfig.json` type checking — JSDoc is documentation only.
+
+## Requirements
+
+**Functional**
+- `npm run lint` runs Biome (existing) + ESLint (new, JSDoc-only rules).
+- ESLint config scoped narrowly: only `jsdoc/*` rules enabled, no stylistic rules (Biome owns those).
+- CI-friendly: lint failures exit non-zero.
+
+**Non-functional**
+- No build step, no emit.
+
+## Architecture
+
+### ESLint config
+
+`eslint.config.js` (flat config, ESLint 9+):
+
+```js
+import jsdoc from "eslint-plugin-jsdoc";
+
+export default [
+  {
+    files: ["src/**/*.js"],
+    plugins: { jsdoc },
+    rules: {
+      "jsdoc/check-alignment": "warn",
+      "jsdoc/check-param-names": "error",
+      "jsdoc/check-tag-names": "error",
+      "jsdoc/check-types": "error",
+      "jsdoc/no-undefined-types": "error",
+      "jsdoc/require-param-type": "error",
+      "jsdoc/require-returns-type": "error",
+      "jsdoc/valid-types": "error",
+    },
+  },
+];
+```
+
+Do NOT require JSDoc on every function — only lint the ones that have it.
+
+### Typedefs to add
+
+Central file: `src/types.js` (JSDoc-only module, re-exported nothing).
+
+- `Env` — Cloudflare bindings + vars (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, `KV`, `DB`, `MODULES`).
+- `Module` — `{ name, init?, commands[], crons? }`.
+- `Command` — `{ name, visibility, description, handler }`.
+- `Cron` — `{ schedule, name, handler }`.
+- `ModuleContext` — `{ db: KVStore, sql: SqlStore, env: Env }`.
+- `KVStore` — existing file; ensure typedef complete.
+- `SqlStore` — created in Phase 01.
+- `Trade` — `{ id, userId, symbol, side, qty, priceVnd, ts }`.
+- `Portfolio` — existing shape.
+
+### Files to annotate
+
+- `src/index.js`
+- `src/bot.js`
+- `src/db/*.js`
+- `src/modules/registry.js`
+- `src/modules/dispatcher.js`
+- `src/modules/cron-dispatcher.js` (from Phase 02)
+- `src/modules/validate-command.js`
+- `src/modules/trading/*.js`
+
+## Related Code Files
+
+**Create**
+- `eslint.config.js`
+- `src/types.js`
+
+**Modify**
+- `package.json` — add `eslint` + `eslint-plugin-jsdoc` devDeps; update `lint` script to `biome check ... && eslint src`
+- All files listed above — add `@param`/`@returns`/`@typedef` where missing
+
+## Todo List
+
+- [x] Install `eslint`, `eslint-plugin-jsdoc`
+- [x] `eslint.config.js` with JSDoc-only rules
+- [x] Update `lint` script
+- [x] `src/types.js` central typedef file
+- [x] Annotate `src/index.js`, `src/bot.js`
+- [x] Annotate `src/db/*`
+- [x] Annotate `src/modules/registry.js`, `dispatcher.js`, `validate-command.js` (skipped `cron-dispatcher.js` — Phase 02 owns it)
+- [x] Annotate `src/modules/trading/*`
+- [x] Run `npm run lint` — clean
+
+## Success Criteria
+
+- `npm run lint` exits 0.
+- Module contract typedef visible to editor tooling (hover shows shape).
+- No new runtime behavior.
+
+## Risks
+
+- ESLint 9 flat config quirks with `eslint-plugin-jsdoc` — pin versions known to work together.