1# Contributing to lofi23This repository runs on a small number of strict habits. They exist so that a prototype built on an4alpha data layer stays honest about what actually works.56## Prerequisites78- **Deno 2.9+** — the only required global runtime.9- **Git** — a contributor prerequisite for this repository journey (generated apps will not need10 it).1112## The one command that gates everything1314```sh15deno task check16```1718This runs formatting, linting, and the deterministic test suite. Deno type-checks the imported19application and runtime modules as part of the suite, which also includes the environment contract20and secret-leak scan. A change is not ready for review until it passes locally. There are no hidden21global tools.2223Before publishing, also inspect the package artifact:2425```sh26deno task publish:dry --allow-dirty27```2829## Contract-driven changes3031The product is defined by [docs/devx-contract.md](docs/devx-contract.md) — a table of falsifiable32promises with IDs, budgets, and statuses. Work relates to it in one of three ways:33341. **Implements a promise.** Cite the contract IDs (e.g. `DX-LOCAL-01`) in the issue and PR, and35 show the evidence that the budget is met.362. **Changes a promise.** Evidence disproved or narrowed it — update the contract row37 (`validated / revised / rejected`) in the same PR and record the delta in a decision record.383. **Touches no promise.** Say so; small mechanical changes do not need contract ceremony.3940### Decision records4142Time-boxed experiments (`type: spike`) must produce a record in43[docs/decisions/](docs/decisions/README.md) with the shape defined there: question, contract IDs,44exact versions, control, procedure, retained evidence, decision, contract delta, follow-up.4546Two rules worth repeating:4748- A spike is complete when it supports a decision — **including a negative decision** — not when a49 demo renders once.50- A search summary without a stable primary source is not evidence. Cite documentation, changelog,51 source, or retained device artifacts.5253## Issues, labels, milestones5455- **Milestones** gate scope: M2 (DevX vertical slice) → M3 (mobile PWA hardening) → M4 (framework56 extraction). Every substantive issue belongs to one.57- **Labels:**58 - `priority: p0` blocks the golden path or the next milestone; `p1` is important milestone work;59 `p2` is follow-up.60 - `area: jazz | pwa | tooling | framework | auth` locates the subsystem.61 - `type: spike` means time-boxed with an explicit decision; `type: devx` means developer62 experience and authoring workflow.63- Issue and PR templates in `.github/` prompt for contract IDs and evidence — filling those fields64 is what makes review fast.6566## Branches and pull requests6768- Branch from `main`; agent-driven work uses the `agent/<scope>` prefix, human work can use any69 clear prefix (`chore/`, `docs/`, `fix/`).70- Merge to `main` happens through a PR. Keep PRs scoped to one milestone concern; link the issues71 they close.72- The PR description should let a reviewer verify claims without re-deriving them: what was run,73 what was observed, where retained evidence lives.7475## Hard boundaries (do not relax casually)7677These are contract commitments, not style preferences:7879- **Secrets:** `JAZZ_ADMIN_SECRET` and `BACKEND_SECRET` are server-only — never projected into80 client config, logs, examples with values, or build output. The secret scan enforces this.81- **Silent degradation is forbidden:** durable storage never quietly becomes memory-only;82 diagnostics never claim signals the pinned vendor API does not expose.83- **The author boundary:** product UI never imports raw Jazz, workers, transports, or Workbox84 config. If a change needs that, it belongs in the runtime layer or an explicitly named escape85 hatch (see the [escape-hatch policy](docs/devx-contract.md#escape-hatch-policy)).86- **Version pins are decisions:** bumping the Jazz alpha (or any pinned tool) requires re-running87 the affected evidence and a decision record if behavior changed.