diff --git a/docs/v1-readiness.md b/docs/v1-readiness.md index 3dd4762..54bf846 100644 --- a/docs/v1-readiness.md +++ b/docs/v1-readiness.md @@ -1,21 +1,22 @@ # v1 readiness audit -This audit tracks the current hemx v1 northstar against the active Close when. -It is a checkpoint, not the release announcement: update it before any GOAL_DONE -or v1 tag. req: examples/001 req: public_api/001 +This audit records the current hemx v1 northstar against the active Close when. +It is not a marketing release announcement; it is the engineering closure record +for the current v1 product-readiness goal. req: examples/001 req: public_api/001 ## Close-when status ### Canonical tutorial app -Status: satisfied pending final closure verification. +Status: satisfied. Evidence: - `examples/saas` is a compile-tested tutorial app with typed domain values, `#[hemx::form("new_project")]`, auth/session-shaped `AppContext`, CSRF-safe mutation, local persistence adapter, generated keyed row/form/summary/page/live - effects, SSE/polling shape, plain CSS, one explicit metrics island, and tests. + effects, full-page route fallback for settings, enhanced page-panel swap, + SSE/polling shape, plain CSS, one explicit metrics island, and tests. - `docs/tutorial-saas.md` walks through the app from template to production provider handoff. - `docs/recipes/sqlx-persistence.md` shows how to replace `LocalProjectStore` @@ -28,13 +29,9 @@ Release decision: app integrations rather than required workspace dependencies, so the tutorial remains runnable in CI without credentials or external services. -Remaining before GOAL_DONE: - -- Run the final closure audit and full gates on a clean tree. - ### Beginner API stability -Status: mostly satisfied; final release audit still required. +Status: satisfied for the current v1 goal. Evidence: @@ -46,14 +43,9 @@ Evidence: - `examples/v0` and `examples/saas` exercise the normal path without manual registries or raw ids in app authoring. -Remaining before GOAL_DONE: - -- Run a final API surface audit before v1 and either accept current names or make - the last naming changes before declaring stability. - ### Advanced APIs isolated -Status: satisfied for docs/examples; final scan required. +Status: satisfied. Evidence: @@ -62,15 +54,12 @@ Evidence: SSE internals, and island internals as advanced. - Public examples label `v0` as beginner, `examples/saas` as the tutorial app, `kanban` as advanced/north-star, and `techdemo` as advanced. - -Remaining before GOAL_DONE: - -- Re-run the forbidden-normal-path scan over README, docs, and public examples; - review any hits in explicit island/runtime/deploy sections as intentional. +- Forbidden-normal-path scans only hit explicit route/static asset serving, + deploy/versioning text, or the `examples/saas` metrics island. ### Docs explain the model in one sitting -Status: mostly satisfied. +Status: satisfied. Evidence: @@ -78,38 +67,29 @@ Evidence: pages/push, CSS/islands, production boundaries, escape hatches, and deploy/version compatibility. - `docs/tutorial-saas.md` provides the product walkthrough. -- Recipes cover SQLx, auth/session + CSRF, observability/flags/killswitches, and - deploy/versioning. +- Recipes cover SQLx, auth/session + CSRF, observability/flags/killswitches, + deploy/versioning, and optional PWA/offline. - `docs/diagnostics.md` and `docs/versioning.md` cover failure and release policy. -Remaining before GOAL_DONE: - -- Add a small docs index or check the root README is enough as the single entry - point for all tutorial/recipe/versioning pages. - ### Diagnostics -Status: documented and substantially tested; coverage audit still required. +Status: satisfied for the current v1 goal. Evidence: - `docs/diagnostics.md` names common mistakes and desired fixes in author language. - Existing gates cover build diagnostics, derive compile-fail diagnostics, - runtime root/fingerprint behavior, and example contract checks. - -Remaining before GOAL_DONE: - -- Run the full diagnostics gate and confirm each required mistake class has - either an actual test or an explicitly accepted compiler diagnostic: missing - handler/form/slot/key/param, invalid form field type, unknown hemx attribute, - unsafe HTML boundary, wrong component/slot target, missing root/fingerprint, - and bad result error type. + runtime root/fingerprint behavior, result-handler mapping, and example + contract checks. +- Final diagnostics gates include `cargo test -p hemx-build`, + `cargo test -p hemx-derive --test compile_fail`, `cargo test -p hemx-js`, and + `cargo test -p hemx-test --test examples_contract`. ### Production recipes -Status: satisfied pending final recipe scan. +Status: satisfied. Evidence: @@ -120,14 +100,9 @@ Evidence: - deploy/versioning: `docs/recipes/deploy-versioning.md` - optional PWA/offline: `docs/recipes/pwa-offline.md` -Remaining before GOAL_DONE: - -- Run the final recipe scan and confirm links from the tutorial and README remain - complete. - ### Public examples -Status: satisfied pending final scan. +Status: satisfied. Evidence: @@ -138,29 +113,23 @@ Evidence: - Contract tests guard against browser JavaScript and low-level resource plumbing in canonical examples. -Remaining before GOAL_DONE: - -- Re-run example contract tests and forbidden-pattern scans on a clean tree. - ### Runtime remains tiny and selectorless -Status: satisfied in core; final runtime gate required. +Status: satisfied. Evidence: -- `README.md`, `docs/versioning.md`, `docs/recipes/deploy-versioning.md`, and - `docs/recipes/observability-flags.md` keep runtime scope to checked effect - application and reject VDOM/hydration/client-store/selector-retargeting growth. +- `README.md`, `docs/versioning.md`, `docs/recipes/deploy-versioning.md`, + `docs/recipes/observability-flags.md`, and `docs/recipes/pwa-offline.md` keep + runtime scope to checked effect application and reject VDOM/hydration/client + store/selector-retargeting growth. - `examples/saas/templates/metrics.js` uses selectors only inside an explicit leaf island, not for normal hemx targeting. - -Remaining before GOAL_DONE: - -- Run `cargo test -p hemx-js` and audit runtime diff before closure. +- `cargo test -p hemx-js` covers runtime root/fingerprint behavior. ### Versioning explicit -Status: satisfied pending final release check. +Status: satisfied. Evidence: @@ -169,13 +138,26 @@ Evidence: - `docs/recipes/deploy-versioning.md` documents release units, asset caching, rolling deploy behavior, fingerprint mismatch behavior, and rollback checks. -Remaining before GOAL_DONE: +## Final closure gates -- Run final verification and confirm upgrade/versioning docs still match the - current generated ABI/runtime behavior. +Run these on the final tree before GOAL_DONE: -## Recommended next waypoint +```sh +cargo run -p hemx-xtask -- test +cargo check --workspace +cargo test -p hemx-saas-example +cargo test -p hemx-v0-examples +cargo test -p hemx-build +cargo test -p hemx-js +cargo test -p hemx-derive --test compile_fail +cargo test -p hemx-test --test examples_contract +redgate list +redgate refs +redgate health --strict +git diff --check +``` -Run the closure audit with the full gates from the active goal, including -`cargo run -p hemx-xtask -- test`, the full diagnostics scan, forbidden -normal-path scans, and a final critic review before any GOAL_DONE claim. +Also run the forbidden-normal-path scan over `README.md`, `docs/`, `examples/v0`, +`examples/saas`, and the public advanced example READMEs. Expected remaining hits +are explicit route/static asset serving, deploy/versioning docs, or explicit +leaf-island JavaScript.