docs(hemx): record final v1 readiness audit
Record the current v1 readiness closure matrix after the final gates and normal-path review, including the release decision for provider recipes and the remaining verification checklist for GOAL_DONE. req: examples/001 req: diagnostics/001 req: public_api/001 req: runtime/003 req: runtime/004
This commit is contained in:
slhx agent
+48
-66
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user