Forecast has no writer — implement the scheduled snapshot flow the object docs promise #590

Found during a full business/platform-capability review of the app (2026-08-02). This is the highest-value functional gap that needs no platform work.

Problem

src/objects/forecast.object.ts:14-16 documents that forecast snapshots are produced by a "forecast.hook.ts scheduled job (default: nightly)". That job does not exist: forecast.hook.ts contains only forecast_derive_period, a beforeInsert/beforeUpdate field-derivation hook. No flow, hook, or job anywhere in src/ ever creates a crm_forecast row.

Consequence: the entire forecasting story — the forecast object, its attainment_pct/coverage_ratio formulas, the forecast_metrics dataset, and the quota-attainment dashboard table — runs on the 3 hand-seeded rows in src/data/index.ts. On any live environment the feature is an empty shell.

Proposed shape

A scheduled flow (weekly or nightly — consistent with the object's own doc comment) that:

1. Enumerates active opportunity owners (users owning at least one open or current-period-closed opportunity).
2. For each owner + current period, aggregates from crm_opportunity: pipeline (open), best_case / commit (by forecast_category), closed_amount (won in period).
3. Upserts on (owner, period) so re-runs are idempotent — same discipline as contract_renewal / opportunity_stagnation.
4. Leaves quota untouched (manually maintained until a quota model exists — separate backlog item).

Follow the repo's sweep conventions: idempotency gate, runAs, and a runtime test in the designated runtime-coverage file (the runtime-coverage.test.ts ratchet will demand one anyway).

Acceptance

• Fresh install + one sweep run ⇒ every active opportunity owner has a current-period crm_forecast row with non-trivial pipeline numbers.
• Re-running the sweep does not duplicate rows.
• forecast.object.ts doc comment matches the implemented schedule.