From dbf7619712519414cbecfbe5304a4228d0eae8bc Mon Sep 17 00:00:00 2001 From: slhx agent Date: Thu, 25 Jun 2026 17:00:18 +0200 Subject: [PATCH] docs(requirements): split test governance rows Add explicit northstar ring fields to test requirements and split browser-selector, surface-generation, browser-E2E, and durable-smoke boundaries without changing behavior. req: test/001 req: test/002 req: test/003 req: test/004 req: test/005 req: test/006 req: test/007 req: test/008 req: test/009 req: test/010 req: test/011 req: test/012 req: test/013 --- AGENTS.md | 4 ++-- REQUIREMENTS.md | 30 +++++++++++++++++++++--------- 2 files changed, 23 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3aed08d..be31762 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,8 +51,8 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - Add only durable style, ownership, gotchas, and at most a few stable commands agents should actually run. - Prefer links or pointers to canonical sources over copied lists. - Avoid project trees, architecture maps, generated inventories, current file sizes, issue lists, TODO inventories, and other snapshots that will rot. -- Stable commands: `cargo run -p hemx-xtask -- test`, `cargo run -p hemx-xtask -- html-examples-smoke`, `cargo check --workspace`, `redgate health --strict`. Use the xtask runner for full verification so jobs are capped from local CPU and memory; use the html_examples smoke for focused browser verification of the HTML pattern gallery. req: test/004 req: test/006 -- Example behavior tests should prefer `hemx_test` generated-resource assertions over raw slot constants or raw effect/payload matching. req: test/008 +- Stable commands: `cargo run -p hemx-xtask -- test`, `cargo run -p hemx-xtask -- html-examples-smoke`, `cargo check --workspace`, `redgate health --strict`. Use the xtask runner for full verification so jobs are capped from local CPU and memory; use the html_examples smoke for focused repo-owned browser verification of the HTML pattern gallery, not `/tmp` scripts. req: test/004 req: test/006 req: test/012 req: test/013 +- Example behavior tests should prefer `hemx_test` generated-resource assertions over raw slot constants or raw effect/payload matching; keep browser selector helpers as test adapters only, not authoring APIs. req: test/008 req: test/009 req: test/010 - Run the workout product exemplar with `cargo run -p hemx-xtask -- workout dev` and open `http://127.0.0.1:3028`; set `HEMX_WORKOUT_ADDR=127.0.0.1:3030` if the default port is busy. Its durable visual direction and recovery expectations live in `examples/workout/DESIGN.md`. req: examples/008 - Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets. req: examples/006 req: examples/011 - hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. Wire output lowers symbolic authoring names to compact metadata and postcard/form-encoded envelopes, not JSON. ABI/schema versions and build fingerprints must guard runtime/server compatibility. req: laws/001 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 req: wire/001 req: wire/002 req: wire/003 req: wire/004 req: wire/005 req: wire/006 req: abi/001 req: abi/002 req: abi/003 req: abi/004 req: abi/005 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index 879cd8e..cfcaecb 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -815,31 +815,43 @@ what a valid business email is. [north_star] ## test ### req: test/001 -001 `EffectWriter` implements a test backend so handlers can be unit-tested without a browser through `hemx_test` run and inspect helpers. [north_star] +0 001 `EffectWriter` implements a test backend so handlers can be unit-tested without a browser through `hemx_test` run and inspect helpers. [north_star] ### req: test/007 -007 `EffectInspector` exposes generated-resource assertions for target updates, HTML/text payloads, keyed insert/replace/remove, navigation, emitted events, slots, and atoms. [north_star] +0 007 `EffectInspector` exposes generated-resource assertions for target updates, HTML/text payloads, keyed insert/replace/remove, navigation, emitted events, slots, and atoms. [north_star] ### req: test/008 -008 Canonical example tests prefer generated-target assertions so tests use the same generated target objects as handlers instead of importing raw slot constants or matching raw effects/payloads. [north_star] +0 008 Canonical example tests prefer generated-target assertions so tests use the same generated target objects as handlers instead of importing raw slot constants or matching raw effects/payloads. [north_star] ### req: test/009 -009 Browser/E2E selector helpers are low-level test adapters only; they are generated or named around public authoring concepts such as handles, targets, forms, nav links, roots, islands, class tokens, or keys, and must not become app authoring APIs. [north_star] +0 009 Browser/E2E selector helpers are low-level adapters only; they are generated or named around public authoring concepts such as handles, targets, forms, nav links, roots, islands, class tokens, or keys. [north_star] + +### req: test/010 +0 010 Browser/E2E selector helpers must not become app authoring APIs. [north_star] ### req: test/002 -002 `#[hemx::component]` may compile without generated Surface files for incremental module-local testing. `#[hemx::surface]` requires `hemx.generated.rs` in `$OUT_DIR` and fails with an actionable diagnostic when generation is missing, because it is the public generated API bridge. +0 002 `#[hemx::component]` may compile without generated Surface files for incremental module-local testing. [north_star] + +### req: test/011 +0 011 `#[hemx::surface]` requires `hemx.generated.rs` in `$OUT_DIR` and fails with an actionable diagnostic when generation is missing. [north_star] ### req: test/003 -003 Generated registries are validated by compile-time tests: missing handler implementations produce test failures with actionable messages. +0 003 Generated registries are validated by compile-time tests: missing handler implementations produce test failures with actionable messages. [north_star] ### req: test/004 -004 Repository-wide verification uses a resource-aware runner that caps Cargo build jobs and Rust test threads from available CPU and memory. User-requested concurrency cannot exceed the detected safe cap. Browser E2E runs as an isolated step and can be skipped explicitly when browser infrastructure is unavailable. +0 004 Repository-wide verification uses a resource-aware runner that caps Cargo build jobs and Rust test threads from available CPU and memory. User-requested concurrency cannot exceed the detected safe cap. [north_star] + +### req: test/012 +0 012 Browser E2E runs as an isolated step and can be skipped explicitly when browser infrastructure is unavailable. [north_star] ### req: test/005 -005 Tests that inspect rendered HTML structure, attributes, escaping, or ordering use DOM-aware parsing such as `scraper` or existing local HTML parsing helpers. Raw string assertions are reserved for tiny literal payload checks where parsing would add noise. [north_star] +0 005 Tests that inspect rendered HTML structure, attributes, escaping, or ordering use DOM-aware parsing such as `scraper` or existing local HTML parsing helpers. Raw string assertions are reserved for tiny literal payload checks. [north_star] ### req: test/006 -006 Repo-owned browser smoke entry points that guard examples use `hemx-xtask` commands, start their own local example server, drive a real browser through the CDP browser tool, and clean up the example process; durable browser coverage must not rely on ad hoc `/tmp` scripts. [north_star] +0 006 Repo-owned browser smoke entry points that guard examples use `hemx-xtask` commands, start their own local example server, drive a real browser through the CDP browser tool, and clean up the example process. [north_star] + +### req: test/013 +0 013 Durable browser coverage must not rely on ad hoc `/tmp` scripts. [north_star] ---