docs(m2): align promotion status with accepted layers
- commit
- dc451e8255a93b562c2cbc1ba17e887e80ec39e7
- parent
- dcc12ac9fa936a0eb1a846680fc88056efa738ab
- parent
- 4e77ebfb029fa0edf485fed283a31351766237be
- author
- FelineStateMachine <dami.etoile@gmail.com>
| M | README.md | 33 | +++++----- |
| M | docs/ | 98 | +++++++++++++++--------------- |
@@ -10,8 +10,8 @@ Built on [Jazz 2](https://jazz.tools) (CRDT data + sync) · [Preact](https://pre
1010 [Astro](https://astro.build) · the [Deno](https://deno.com) toolchain.1111 1212 > **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).13+> (feasibility) are complete; all three M2 source layers are merged on `m2` and undergoing combined14+> promotion review. See the [roadmap](#roadmap).1515 1616 ## Why lofi1717 @@ -42,8 +42,9 @@ required global runtime and a command surface of exactly seven verbs: `create`,
4242 4343 ## Try it today (checkout journey)4444 45-The M2 branch now contains the source generator and its package-owned commands, but the package is46-not published while Layer 2 is under review. The currently available journey runs from a checkout:45+The `m2` branch contains the accepted source generator, package-owned commands, development46+inspector, and browser-testing helpers. The package is not published until explicitly authorized and47+the registry-backed smoke passes, so the currently available journey runs from a checkout:4748 4849 ```sh4950 git clone https://github.com/FelineStateMachine/lofi.git@@ -68,9 +69,9 @@ deno task dev
6869 | `deno task build` | Production build through the supported Deno path. |6970 | `deno task preview` | Serves the production build. |7071 71-`create` and `doctor` are implemented in the M2 source package. They graduate only after the72-generated-project golden journey, clean-room review, and registry-backed smoke pass; their output73-contracts are specified in the72+`create` and `doctor` have graduated through the source-backed generated-project golden journey and73+clean-room review. The public JSR invocation remains unavailable until publication and its74+registry-backed smoke pass; the output contracts are specified in the7475 [DevX contract](docs/devx-contract.md#canonical-command-surface-and-output-contract).7576 7677 ## How this repository works@@ -88,18 +89,18 @@ graduates only by producing evidence against them.
8889 8990 Notable honest outcomes so far: the Jazz 2 alpha passkey-backup ceremony was **rejected** on9091 security grounds rather than demoed91-([decision 0004](docs/decisions/0004-reject-alpha53-passkey-backup.md)), and transport reconnection92-is reported as _unavailable_ rather than faked, because the pinned API exposes no such signal.92+([decision 0004](docs/decisions/0004-reject-alpha53-passkey-backup.md)), and live transport state is93+reported as _unavailable_ rather than faked, because the pinned API exposes no supported signal.9394 9495 ## Roadmap9596 96-| Milestone | Goal | Status |97-| ----------------------------- | -------------------------------------------------------------------------------------------------- | -------------- |98-| **M0 — DevX contract** | Define the golden path, command surface, environment contract, and measurable acceptance criteria. | ✅ Done |99-| **M1 — Feasibility spikes** | Prove Jazz 2, Preact, OPFS, identity, Astro islands, and Deno behavior with go/no-go decisions. | ✅ Done |100-| **M2 — DevX vertical slice** | `create`, `dev`, `doctor`, diagnostics, inspector, and testing workflows around a reference app. | 🚧 In progress |101-| **M3 — Mobile PWA hardening** | Install, persistence, offline cold start, lifecycle recovery, and physical-device validation. | ⏳ Queued |102-| **M4 — Framework extraction** | Extract proven seams into `@nzip/lofi` subpath exports; validate them through a second app. | ⏳ Queued |97+| Milestone | Goal | Status |98+| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------- |99+| **M0 — DevX contract** | Define the golden path, command surface, environment contract, and measurable acceptance criteria. | ✅ Done |100+| **M1 — Feasibility spikes** | Prove Jazz 2, Preact, OPFS, identity, Astro islands, and Deno behavior with go/no-go decisions. | ✅ Done |101+| **M2 — DevX vertical slice** | `create`, `dev`, `doctor`, diagnostics, inspector, and testing workflows around a reference app. | 🧪 Promotion review |102+| **M3 — Mobile PWA hardening** | Install, persistence, offline cold start, lifecycle recovery, and physical-device validation. | ⏳ Queued |103+| **M4 — Runtime API extraction** | Extract remaining proven runtime seams as `@nzip/lofi` subpaths; validate them through a second app. | ⏳ Queued |103104 104105 The definition of done for the whole prototype is the [north star](#the-north-star) journey passing105106 its contract budgets end-to-end, on real devices.@@ -1,6 +1,6 @@
11 # lofi developer-experience contract22 3-Status: **v0 validated through M1; M2 implementation in progress**\3+Status: **v0 validated through the M2 source layers; combined promotion review in progress**\44 Scope: **M0 contract, M1 feasibility, and M2 DevX graduation**\55 Last reviewed: **2026-07-15**66 @@ -26,8 +26,8 @@ honesty of the graduated reference application.
2626 2727 ### North-star generated-project journey2828 29-This is the eventual product experience. The generator itself is M2 work and is not claimed as an M130-deliverable.29+This is the product experience validated from M2 source. The registry command remains unavailable30+until the first explicitly authorized publish and registry-backed smoke.3131 3232 ```sh3333 deno run -A jsr:@nzip/lofi/create my-app@@ -35,10 +35,10 @@ cd my-app
3535 deno task dev3636 ```3737 38-The planned JSR surface is one package, `@nzip/lofi`, with one version and publish operation.39-Framework and tooling boundaries are subpath exports—starting with `./create`, `./core`, `./sync`,40-`./auth`, `./ui`, `./pwa`, and `./testing`—rather than lockstep packages. See41-[ADR 0005](decisions/0005-publish-one-nzip-lofi-package.md).38+The JSR surface is one package, `@nzip/lofi`, with one version and publish operation. M2 validates39+the command subpaths plus `./testing`; remaining runtime subpaths such as `./core`, `./sync`,40+`./auth`, `./ui`, and `./pwa` graduate only when M4 proves their seams through another application.41+See [ADR 0005](decisions/0005-publish-one-nzip-lofi-package.md).4242 4343 From there the developer makes a retained local write, reloads it, works offline, runs checks,4444 builds, previews, and opens the same stable secure origin on a physical device.@@ -92,34 +92,34 @@ required global runtime for a generated application.
9292 9393 ## Measurable promises9494 95-| ID | Promise | v0 budget or condition | Evidence owner | M1 gate | Status |96-| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------- | --------- |97-| DX-CREATE-01 | Named creation is non-interactive. | Deno is the only required global runtime; zero prompts; uncached time reported. | M2 | no | proposed |98-| DX-CMD-01 | The public command surface is small. | create, dev, doctor, check, test, build, preview only. | #2 and #6 | yes | validated |99-| DX-TTFW-01 | Generated create-to-retained-write is fast. | At most three shell commands and two minutes on the recorded machine/network. | M2 | no | proposed |100-| DX-PROTOTYPE-01 | The M1 checkout reaches a retained write quickly. | `deno task dev` to retained write within 60 seconds after cached setup. | integrated M1 prototype | yes | validated |101-| DX-START-01 | Cached development startup feels immediate. | Warm median at most 2 seconds; slowest at most 5 seconds across five samples. | #6 | yes | validated |102-| DX-HMR-01 | UI edits retain state and runtime cardinality. | Median feedback at most 300 ms; one client and one vendor subscription per shared query after five edits. | #5 and #6 | yes | validated |103-| DX-AUTHOR-01 | Product edits avoid framework plumbing. | The integrated task changes only schema, app config, page/island, style, or test files. | integrated prototype | yes | validated |104-| DX-LEAK-01 | Runtime machinery stays outside product UI. | No provider, raw client, worker, transport URL, Workbox config, or browser branch in product UI. | #5, #6, integration | yes | validated |105-| DX-LOCAL-01 | Local work does not await network/auth round trips. | Subscribed UI reflects an offline write in the same event turn or next render; reload retains it. | #7 | yes | validated |106-| DX-DUR-01 | Durable mode never silently becomes ephemeral. | Boot reports durable, unsupported, or explicitly opted-in memory mode. | #4 and #7 | yes | validated |107-| DX-SYNC-01 | Application-data transport has one lofi-owned surface. | App config selects a named adapter; product UI never constructs peers or transports. | #7 and integration | yes | validated |108-| DX-OBS-01 | Diagnostics expose only truthful signals. | Configured state and per-write durability map to public APIs; unavailable transport detail is named. | #7 | yes | validated |109-| DX-ENV-01 | Environment handling is safe by construction. | Real env ignored; allowlisted loader; server values absent from client projection and built output. | #3, #7, final build | yes | validated |110-| DX-ERROR-01 | Failures state capability, impact, and action. | No secret values; common config recovery is one edit plus rerun. | #3, #4, #6 | yes | validated |111-| DX-AUTH-01 | Identity wording matches custody/recovery. | UI identifies the device-local key, blocks the rejected alpha passkey path, and defines any future phrase as an identity bearer secret rather than data backup. | #8 | yes | revised |112-| DX-DEVICE-01 | Device/auth tests use a stable, appropriately isolated origin. | M1 proves a stable HTTPS PWA scope for OPFS; installed-app RP-ID preservation and identity isolation remain required before any replacement passkey ceremony. | #4 and #8 | yes | revised |113-| DX-DEVICE-UX-01 | Device preview is one productized command. | Primary path prints stable URL, capability report, and remediation. | M3 | no | proposed |114-| DX-OFFLINE-01 | Installed production cold-start renders retained data offline. | Airplane-mode launch renders shell and data. | feasibility #4; full M3 | no | proposed |115-| DX-BUILD-01 | Development and production share the Deno command contract. | `deno task build` and `preview`; no undocumented Node command. | #6 | yes | validated |116-| DX-TEST-01 | Local-first tests avoid hand-timed sleeps. | Readiness-based offline/two-client primitives. | feasibility #7; M2 implementation | no | proposed |95+| ID | Promise | v0 budget or condition | Evidence owner | M1 gate | Status |96+| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- | --------- |97+| DX-CREATE-01 | Named creation is non-interactive. | Deno is the only required global runtime; zero prompts; uncached time reported. | M2 source; cold registry pending | no | proposed |98+| DX-CMD-01 | The public command surface is small. | create, dev, doctor, check, test, build, preview only. | #2 and #6 | yes | validated |99+| DX-TTFW-01 | Generated create-to-retained-write is fast. | At most three shell commands and two minutes on the recorded machine/network. | M2 source; cold registry pending | no | proposed |100+| DX-PROTOTYPE-01 | The M1 checkout reaches a retained write quickly. | `deno task dev` to retained write within 60 seconds after cached setup. | integrated M1 prototype | yes | validated |101+| DX-START-01 | Cached development startup feels immediate. | Warm median at most 2 seconds; slowest at most 5 seconds across five samples. | #6 | yes | validated |102+| DX-HMR-01 | UI edits retain state and runtime cardinality. | Median feedback at most 300 ms; one client and one vendor subscription per shared query after five edits. | #5 and #6 | yes | validated |103+| DX-AUTHOR-01 | Product edits avoid framework plumbing. | The integrated task changes only schema, app config, page/island, style, or test files. | integrated prototype | yes | validated |104+| DX-LEAK-01 | Runtime machinery stays outside product UI. | No provider, raw client, worker, transport URL, Workbox config, or browser branch in product UI. | #5, #6, integration | yes | validated |105+| DX-LOCAL-01 | Local work does not await network/auth round trips. | Subscribed UI reflects an offline write in the same event turn or next render; reload retains it. | #7 | yes | validated |106+| DX-DUR-01 | Durable mode never silently becomes ephemeral. | Boot reports durable, unsupported, or explicitly opted-in memory mode. | #4 and #7 | yes | validated |107+| DX-SYNC-01 | Application-data transport has one lofi-owned surface. | App config selects a named adapter; product UI never constructs peers or transports. | #7 and integration | yes | validated |108+| DX-OBS-01 | Diagnostics expose only truthful signals. | Configured state and per-write durability map to public APIs; unavailable transport detail is named. | #7 | yes | validated |109+| DX-ENV-01 | Environment handling is safe by construction. | Real env ignored; allowlisted loader; server values absent from client projection and built output. | #3, #7, final build | yes | validated |110+| DX-ERROR-01 | Failures state capability, impact, and action. | No secret values; common config recovery is one edit plus rerun. | #3, #4, #6 | yes | validated |111+| DX-AUTH-01 | Identity wording matches custody/recovery. | UI identifies the device-local key, blocks the rejected alpha passkey path, and defines any future phrase as an identity bearer secret rather than data backup. | #8 | yes | revised |112+| DX-DEVICE-01 | Device/auth tests use a stable, appropriately isolated origin. | M1 proves a stable HTTPS PWA scope for OPFS; installed-app RP-ID preservation and identity isolation remain required before any replacement passkey ceremony. | #4 and #8 | yes | revised |113+| DX-DEVICE-UX-01 | Device preview is one productized command. | Primary path prints stable URL, capability report, and remediation. | M3 | no | proposed |114+| DX-OFFLINE-01 | Installed production cold-start renders retained data offline. | Airplane-mode launch renders shell and data. | feasibility #4; full M3 | no | proposed |115+| DX-BUILD-01 | Development and production share the Deno command contract. | `deno task build` and `preview`; no undocumented Node command. | #6 | yes | validated |116+| DX-TEST-01 | Local-first tests avoid hand-timed sleeps. | Readiness-based offline/two-client primitives. | #7 and M2 Layer 3 | no | validated |117117 118118 ## Canonical command surface and output contract119119 120-These are product outputs, not claims that every command is implemented at Contract v0. The M1121-prototype must implement `dev`, `check`, `test`, `build`, and `preview`; `create` and the complete122-`doctor` experience graduate in M2.120+These outputs are implemented and verified from M2 source. The `create` registry invocation remains121+conditional on an explicitly authorized publish and registry-backed smoke; the generated command122+surface itself is covered by the source-backed golden journey.123123 124124 | Command | Success output must contain | Failure output must contain |125125 | ------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------- |@@ -217,9 +217,9 @@ Missing public configuration selects local-only mode if #7 verifies support. Par
217217 cloud configuration is `invalid`, stops the relevant command, and cannot be projected into client218218 config. Server-only values without client configuration remain isolated and produce a warning.219219 220-Root-repository ignore and leak tests do not satisfy the generated-project/release-artifact portion221-of #3. That acceptance item remains open until the M1 prototype produces a build to inspect; the M2222-generator gets its own fixture inspection.220+Root-repository ignore and leak tests are supplemented by generated-project fixture inspection,221+production build scanning, and retained-artifact scans. Publication still requires a fresh registry222+smoke and release-artifact review; source acceptance does not imply that a package exists on JSR.223223 224224 ## Escape-hatch policy225225 @@ -282,14 +282,15 @@ Jazz version, Preact strategy, Astro/Deno path, durability policy, and identity
282282 runtime alternatives are removed from the final tree; their evidence remains in decisions and283283 merge-commit history.284284 285-Package extraction, the generator, full inspector/testing SDK, and production PWA hardening remain286-M2 or later work.285+M2 has graduated the single-package command surface, generator, development inspector, and286+readiness-first browser-testing helpers. Production PWA/device hardening remains M3 work; remaining287+runtime package seams and a second consumer remain M4 work.287288 288289 ## M2 layered graduation289290 290-M2 integrates into the `m2` branch as three separately reviewed layers. Each layer must pass its own291-checks and independent pull-request review before merge. The combined branch is re-reviewed before292-it may merge into `dev`.291+M2 integrated into the `m2` branch as three separately reviewed layers. Each layer passed its own292+checks and independent pull-request review before merge. The combined branch is now being293+re-reviewed before it may merge into `dev`.293294 294295 Layer verification runs outside the product and framework surface. An independent agent checks the295296 exact pushed head in a detached Git worktree, runs `deno task check` plus the layer's applicable@@ -299,15 +300,16 @@ workflow on the framework or generated applications. A layer may merge only when
299300 result and independent review accept that exact head. The final `m2` combination repeats the same300301 clean-room and review boundary before promotion to `dev`.301302 302-| Layer | Issues | Contract result |303-| ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |304-| 1 — reference and checkout journey | #9; tracks #11 | Honest checklist CRUD, explicit author/generated boundary, and reusable checkout-mode golden-path evidence. |305-| 2 — public command path | #13, #14; completes #11 | Non-interactive creation plus actionable `dev`/`doctor`; the same journey runs against generated output. |306-| 3 — testing and inspection | #12, #10 | Reusable offline/convergence controls and truthful developer diagnostics without leaking machinery into product UI. |303+| Layer | Issues | Contract result |304+| ---------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------- |305+| 1 — reference and checkout journey | #9; tracks #11 | Honest checklist CRUD, explicit author/generated boundary, and reusable checkout-mode golden-path evidence. |306+| 2 — public command path | #13, #14; source gate for #11 | Non-interactive creation plus actionable `dev`/`doctor`; the same journey runs against generated output. |307+| 3 — testing and inspection | #12, #10 | Reusable offline/convergence controls and truthful developer diagnostics without leaking machinery into product UI. |307308 308-Layer 1 does not close #11: checkout-mode evidence is necessary, but the generated-project journey309-cannot pass until Layer 2 implements the public create command. Remaining abstraction leaks are310-tracked in `docs/m2-abstraction-leaks.md` rather than hidden behind premature package APIs.309+Layer 1 alone did not close #11: checkout-mode evidence was necessary, and Layer 2 subsequently310+passed the source-backed generated-project journey. Registry-backed acceptance remains conditional311+on explicit publication authorization. Remaining abstraction leaks are tracked in312+`docs/m2-abstraction-leaks.md` rather than hidden behind premature package APIs.311313 312314 Layer 2 has two distinct package gates. Before publication, the generated-project journey invokes313315 the real local `./create` entrypoint and uses an explicitly test-only file-URL package override so