Give the repository a front door that reflects the contract-driven workflow: north-star journey, current milestone status, command surface, and evidence discipline. Issue forms and the PR template prompt for contract IDs and retained evidence.
- commit
- 1e2231588922c6863a39bb58d123f6da48d5b0fc
- parent
- 33fdd3593240e7abf4bd92eab0c3c38d85472333
- author
- Dami <dami.etoile@gmail.com>
| A | .github/ | 5 | + |
| A | .github/ | 35 | ++++++++ |
| A | .github/ | 50 | +++++++++++ |
| A | .github/ | 20 | +++++ |
| A | CONTRIBUTING.md | 80 | ++++++++++++++++++ |
| A | README.md | 133 | ++++++++++++++++++++++++++++++ |
@@ -0,0 +1,35 @@
1+name: Milestone task2+description: Implementation or documentation work that advances a milestone3+body:4+ - type: textarea5+ id: outcome6+ attributes:7+ label: Outcome8+ description: What exists (and is observable) when this issue closes.9+ validations:10+ required: true11+ - type: input12+ id: contract-ids13+ attributes:14+ label: Contract IDs15+ description: >-16+ Promises from docs/devx-contract.md this work implements or changes. Write "none" for17+ mechanical changes.18+ placeholder: DX-CMD-01, DX-CREATE-0119+ validations:20+ required: true21+ - type: textarea22+ id: acceptance23+ attributes:24+ label: Acceptance criteria25+ description: Checkable statements a reviewer can verify without re-deriving the work.26+ placeholder: |27+ - [ ] `deno task doctor` prints a versioned capability table without values28+ - [ ] Nonzero exit for blockers29+ validations:30+ required: true31+ - type: textarea32+ id: out-of-scope33+ attributes:34+ label: Out of scope35+ description: Adjacent work this issue deliberately does not claim.@@ -0,0 +1,50 @@
1+name: Spike2+description: A time-boxed experiment that must end in an explicit decision3+labels: ["type: spike"]4+body:5+ - type: input6+ id: question7+ attributes:8+ label: Question9+ description: The falsifiable choice or platform claim this spike resolves.10+ placeholder: Does Jazz 2 OPFS persistence survive process kill on iOS Safari 16.4?11+ validations:12+ required: true13+ - type: input14+ id: contract-ids15+ attributes:16+ label: Contract IDs17+ description: Promises from docs/devx-contract.md this spike exercises.18+ placeholder: DX-DUR-01, DX-ERROR-0119+ validations:20+ required: true21+ - type: textarea22+ id: control23+ attributes:24+ label: Control25+ description: The smallest vendor-supported baseline the experiment is compared against.26+ validations:27+ required: true28+ - type: textarea29+ id: kill-criteria30+ attributes:31+ label: Decision / kill criteria32+ description: What result adopts, revises, defers, or rejects — decided before running.33+ validations:34+ required: true35+ - type: textarea36+ id: evidence-plan37+ attributes:38+ label: Evidence plan39+ description: >-40+ What will be retained (paths, measurements, device logs/screenshots, commit SHA) so someone41+ else can repeat it. A demo rendering once is not evidence.42+ validations:43+ required: true44+ - type: input45+ id: timebox46+ attributes:47+ label: Timebox48+ placeholder: 2 days49+ validations:50+ required: true@@ -0,0 +1,20 @@
1+## Summary2+3+<!-- What changed and why, in terms a reviewer can verify. Link the issues this closes. -->4+5+## Contract impact6+7+<!-- Contract IDs implemented or changed (e.g. DX-LOCAL-01), with status transitions8+ (proposed → validated / revised / rejected). Write "none" for mechanical changes. -->9+10+## Evidence11+12+<!-- What was run and observed; where retained evidence lives (paths, measurements,13+ decision record). "Worked once" is not evidence. -->14+15+## Checklist16+17+- [ ] `deno task check` passes locally18+- [ ] Contract table and decision records updated if any promise changed19+- [ ] No server-only secret value appears in code, examples, logs, or build output20+- [ ] Product UI stays inside the author boundary (no raw Jazz / workers / transports / Workbox)@@ -0,0 +1,80 @@
1+# Contributing to lofi2+3+This repository runs on a small number of strict habits. They exist so that a prototype built on an4+alpha data layer stays honest about what actually works.5+6+## Prerequisites7+8+- **Deno 2.9+** — the only required global runtime.9+- **Git** — a contributor prerequisite for this repository journey (generated apps will not need10+ it).11+12+## The one command that gates everything13+14+```sh15+deno task check16+```17+18+This runs formatting, linting, type checks, Astro checks, the deterministic test suite, the19+environment-contract check, and the secret-leak scan. A change is not ready for review until it20+passes locally. There are no other hidden global tools.21+22+## Contract-driven changes23+24+The product is defined by [docs/devx-contract.md](docs/devx-contract.md) — a table of falsifiable25+promises with IDs, budgets, and statuses. Work relates to it in one of three ways:26+27+1. **Implements a promise.** Cite the contract IDs (e.g. `DX-LOCAL-01`) in the issue and PR, and28+ show the evidence that the budget is met.29+2. **Changes a promise.** Evidence disproved or narrowed it — update the contract row30+ (`validated / revised / rejected`) in the same PR and record the delta in a decision record.31+3. **Touches no promise.** Say so; small mechanical changes do not need contract ceremony.32+33+### Decision records34+35+Time-boxed experiments (`type: spike`) must produce a record in36+[docs/decisions/](docs/decisions/README.md) with the shape defined there: question, contract IDs,37+exact versions, control, procedure, retained evidence, decision, contract delta, follow-up.38+39+Two rules worth repeating:40+41+- A spike is complete when it supports a decision — **including a negative decision** — not when a42+ demo renders once.43+- A search summary without a stable primary source is not evidence. Cite documentation, changelog,44+ source, or retained device artifacts.45+46+## Issues, labels, milestones47+48+- **Milestones** gate scope: M2 (DevX vertical slice) → M3 (mobile PWA hardening) → M4 (framework49+ extraction). Every substantive issue belongs to one.50+- **Labels:**51+ - `priority: p0` blocks the golden path or the next milestone; `p1` is important milestone work;52+ `p2` is follow-up.53+ - `area: jazz | pwa | tooling | framework | auth` locates the subsystem.54+ - `type: spike` means time-boxed with an explicit decision; `type: devx` means developer55+ experience and authoring workflow.56+- Issue and PR templates in `.github/` prompt for contract IDs and evidence — filling those fields57+ is what makes review fast.58+59+## Branches and pull requests60+61+- Branch from `main`; agent-driven work uses the `agent/<scope>` prefix, human work can use any62+ clear prefix (`chore/`, `docs/`, `fix/`).63+- Merge to `main` happens through a PR. Keep PRs scoped to one milestone concern; link the issues64+ they close.65+- The PR description should let a reviewer verify claims without re-deriving them: what was run,66+ what was observed, where retained evidence lives.67+68+## Hard boundaries (do not relax casually)69+70+These are contract commitments, not style preferences:71+72+- **Secrets:** `JAZZ_ADMIN_SECRET` and `BACKEND_SECRET` are server-only — never projected into73+ client config, logs, examples with values, or build output. The secret scan enforces this.74+- **Silent degradation is forbidden:** durable storage never quietly becomes memory-only;75+ diagnostics never claim signals the pinned vendor API does not expose.76+- **The author boundary:** product UI never imports raw Jazz, workers, transports, or Workbox77+ config. If a change needs that, it belongs in the runtime layer or an explicitly named escape78+ hatch (see the [escape-hatch policy](docs/devx-contract.md#escape-hatch-policy)).79+- **Version pins are decisions:** bumping the Jazz alpha (or any pinned tool) requires re-running80+ the affected evidence and a decision record if behavior changed.@@ -0,0 +1,133 @@
1+# lofi2+3+**A local-first mobile PWA meta-framework, built as an honest prototype.**4+5+Write a schema, build Preact islands, ship an installable offline-capable app. The UI always6+hydrates from local data, identity never waits on a server, and the sync module is the only network7+surface an app developer ever sees.8+9+Built on [Jazz 2](https://jazz.tools) (CRDT data + sync) · [Preact](https://preactjs.com) islands in10+[Astro](https://astro.build) · the [Deno](https://deno.com) toolchain.11+12+> **Status: working prototype, pre-release.** Nothing is published yet. M0 (DevX contract) and M113+> (feasibility) are complete and merged; M2 (DevX vertical slice) is in active development. See the14+> [roadmap](#roadmap).15+16+## Why lofi17+18+- **Local-first without the plumbing.** Product code touches schema, config, islands, styles, and19+ tests — never providers, workers, transports, or service-worker internals20+ ([DX-AUTHOR-01, DX-LEAK-01](docs/devx-contract.md#measurable-promises)).21+- **Honest by construction.** Durable storage never silently degrades to memory; diagnostics only22+ claim what the underlying APIs can actually observe; identity wording matches real custody and23+ recovery semantics.24+- **Mobile PWA first.** Platform floors (Android Chrome 148+, iOS Safari 16.4+) are enforced boot25+ gates, not advisory footnotes. Unsupported browsers get an explicit answer, never silent data26+ loss.27+28+## The north star29+30+When every milestone below has landed, this is the entire onboarding experience:31+32+```sh33+deno run -A jsr:@lofi/create my-app34+cd my-app35+deno task dev36+```37+38+From there a developer makes a retained local write, reloads it, works offline, runs checks, builds,39+previews, and opens the same stable secure origin on a physical phone — with Deno as the only40+required global runtime and a command surface of exactly seven verbs: `create`, `dev`, `doctor`,41+`check`, `test`, `build`, `preview`.42+43+## Try it today (M1 journey)44+45+The generator does not exist yet; the graduated prototype runs from a checkout:46+47+```sh48+git clone https://github.com/FelineStateMachine/lofi.git49+cd lofi50+deno task dev51+```52+53+- **Deno 2.9+** is the only required global runtime.54+- **No `.env` means local-only mode**, stated explicitly at boot. For cloud sync, copy55+ `.env.example` and set the public `JAZZ_APP_ID`/`JAZZ_SERVER_URL` pair. Server-only secrets never56+ reach client output — this is tested, not hoped.57+- From `deno task dev` you should reach a retained local write in under 60 seconds58+ ([DX-PROTOTYPE-01](docs/devx-contract.md#measurable-promises)).59+60+### Command surface61+62+| Command | What it does today |63+| ------------------- | ------------------------------------------------------------------------ |64+| `deno task dev` | Serves the prototype; prints URL plus storage, identity, and sync state. |65+| `deno task check` | Format, lint, type, Astro, env-contract, and secret-leak checks. |66+| `deno task test` | Deterministic local-first tests (no hand-timed sleeps). |67+| `deno task build` | Production build through the supported Deno path. |68+| `deno task preview` | Serves the production build. |69+70+`create` and `doctor` graduate in M2 — their output contracts are already specified in the71+[DevX contract](docs/devx-contract.md#canonical-command-surface-and-output-contract).72+73+## How this repository works74+75+Development here is **contract-driven**: the product is a set of falsifiable promises, and code76+graduates only by producing evidence against them.77+78+1. **[The DevX contract](docs/devx-contract.md)** defines measurable promises with IDs (like79+ `DX-LOCAL-01`), budgets, and statuses (`proposed → validated / revised / rejected`).80+2. **[Decision records](docs/decisions/)** capture each experiment: question, exact versions,81+ control, procedure, retained evidence, and the resulting contract delta. A spike is complete when82+ it supports a decision — including a negative one — not when a demo renders once.83+3. **[Milestones](https://github.com/FelineStateMachine/lofi/milestones)** gate scope. Issues carry84+ `area:*`, `type:*`, and `priority:p0–p2` labels; p0 blocks the golden path.85+86+Notable honest outcomes so far: the Jazz 2 alpha passkey-backup ceremony was **rejected** on87+security grounds rather than demoed88+([decision 0004](docs/decisions/0004-reject-alpha53-passkey-backup.md)), and transport reconnection89+is reported as _unavailable_ rather than faked, because the pinned API exposes no such signal.90+91+## Roadmap92+93+| Milestone | Goal | Status |94+| ----------------------------- | ---------------------------------------------------------------------------------------------------- | -------------- |95+| **M0 — DevX contract** | Define the golden path, command surface, environment contract, and measurable acceptance criteria. | ✅ Done |96+| **M1 — Feasibility spikes** | Prove Jazz 2, Preact, OPFS, identity, Astro islands, and Deno behavior with go/no-go decisions. | ✅ Done |97+| **M2 — DevX vertical slice** | `create`, `dev`, `doctor`, diagnostics, inspector, and testing workflows around a reference app. | 🚧 In progress |98+| **M3 — Mobile PWA hardening** | Install, persistence, offline cold start, lifecycle recovery, and physical-device validation. | ⏳ Queued |99+| **M4 — Framework extraction** | Extract proven seams into `@lofi/*` packages; validate them through a second generated consumer app. | ⏳ Queued |100+101+The definition of done for the whole prototype is the [north star](#the-north-star) journey passing102+its contract budgets end-to-end, on real devices.103+104+## Repository map105+106+```text107+lofi/108+├── docs/109+│ ├── devx-contract.md # The product contract: promises, budgets, statuses110+│ └── decisions/ # Evidence-backed decision records (ADR-style)111+├── apps/prototype/ # The integrated app graduated from M1 (M2 reshapes this)112+├── spikes/ # M1 feasibility experiments, kept for evidence113+├── tools/ # Deno tasks: env contract, secret scanning, runners114+├── init.md # Original research plan — input, not the contract115+└── deno.json # Workspace tasks and pinned toolchain116+```117+118+## Stack119+120+| Layer | Choice | Pinned at |121+| ---------- | --------------------------------------------- | ------------------- |122+| Data/sync | jazz-tools 2.0 alpha (exact pin), OPFS | `2.0.0-alpha.53` |123+| UI runtime | Preact islands, `client:only`, thin adapter | Preact 10 / Astro 7 |124+| Shell | Astro, fully prerendered, static-through-Deno | Astro 7 |125+| Toolchain | Deno tasks + npm-compat | Deno 2.9 |126+127+Version pins are deliberate: the data layer is an alpha, so every bump is a reviewed decision, and128+`docs/decisions/` records what each pin was verified to do.129+130+## Contributing131+132+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow: how promises, evidence, and decision133+records fit together, what `deno task check` enforces, and how issues and milestones are organized.