docs(work): map testing and editor northstars

Add repo-local northstars and ready slices for testing strategy, LSP/editor completion, and hemplate highlighting boundaries.
2026-06-25 22:20:50 +02:00
parent edc65be7b6
commit df0fabd4fb
15 changed files with 622 additions and 0 deletions
@@ -0,0 +1,49 @@
 ---
 id: NS-0001
 type: northstar
 status: ready
 title: Testing strategy confidence ladder
 refs:
  - REQUIREMENTS.md
  - AGENTS.md
  - README.md
  - hemx-xtask/src/main.rs
  - hemx-test/src/lib.rs
  - examples/html_examples/README.md
 ---
 ## Objective
 Make hemx verification boring and reliable by keeping a documented confidence ladder from fast crate tests, through focused browser/runtime smoke, to the full `cargo run -p hemx-xtask -- test` authority. The outcome is not more test ceremony; it is clear proof selection for agents and contributors.
 ## Authority
 - `AGENTS.md` and `README.md` define stable verification commands, focused browser smoke, full xtask authority, and the 10 minute local full-check budget.
 - `REQUIREMENTS.md` `test/001` through `test/017` constrain generated-resource assertions, examples, browser smoke, no `/tmp` scripts, no-reload interactions, tiers, shard expectations, and diagnostic quality.
 - `hemx-xtask/src/main.rs` owns repo-capped verification commands and `html-examples-smoke`.
 - `hemx-test/src/lib.rs` owns reusable test inspection helpers.
 ## Close when
 - Fast, focused browser, and full verification tiers have ready slices with exact commands and ownership boundaries.
 - Browser/runtime confidence covers no-reload dynamic interactions, revealed fallback, interval/timing behavior, and generated target assertions.
 - Regression boundaries prefer generated-resource assertions and `hemx_test` helpers over raw ids or raw effect matching.
 - Requirement/test governance stays tied to redgate health/lint without turning lint cleanup into product work.
 ## Verification
 - `work check`
 - `work list`
 - Later implementation slices choose the narrowest relevant command, then use `cargo run -p hemx-xtask -- test` when changing shared verification authority.
 ## Non-goals
 - Do not add a parallel test runner outside `hemx-xtask`.
 - Do not replace meaningful behavior tests with mocks-only assertions.
 - Do not make redgate warnings the product outcome unless the slice explicitly owns requirement maintainability.
 ## Evidence
 - `cargo run -p hemx-xtask -- html-examples-smoke` is the focused browser proof for html_examples dynamic behavior.
 - `cargo run -p hemx-xtask -- test` is the full local authority wrapper.
 - `redgate health --strict` and `redgate lint` are governance proof commands.
@@ -0,0 +1,50 @@
 ---
 id: NS-0002
 type: northstar
 status: ready
 title: LSP and editor experience completion
 refs:
  - REQUIREMENTS.md
  - docs/editor-support.md
  - docs/diagnostics.md
  - docs/hemplate-syntax.md
  - hemx-lsp/src/main.rs
  - hemx-build/src/lib.rs
 ---
 ## Objective
 Complete the `.heml` editor experience around existing compiler/build authority: diagnostics parity, completion, hover, cross-file facts, and correct LSP protocol behavior without inventing a second template language or editor framework.
 ## Authority
 - `docs/editor-support.md` says `.heml` authoring should feel like HTML first and layer hemx diagnostics/completions/hover on top.
 - `docs/hemplate-syntax.md` is the stable syntax surface; LSP must not invent Vue/Handlebars-like syntax.
 - `docs/diagnostics.md` keeps editor overlays subordinate to compiler/build diagnostics.
 - `REQUIREMENTS.md` `diagnostics/004` through `diagnostics/008` and `check/001`/`check/003` constrain editor overlays, spans, completion, hover, and build-visible validation.
 - `hemx-lsp/src/main.rs` currently owns the CLI/LSP implementation surface.
 ## Close when
 - Diagnostics parity slices prove LSP-published diagnostics match `hemx-build` CLI diagnostics for open/save/file paths.
 - Completion slices cover hemplate directives, `data-hemx-*` attributes, and context-sensitive generated facts without requiring external editor state.
 - Hover slices explain real hemplate syntax and hemx attributes from docs authority.
 - Cross-file fact slices describe what must fail at `cargo check` and what can remain editor-only.
 - LSP protocol slices cover initialize, sync, completion, hover, diagnostics clearing, and error responses with tests.
 ## Verification
 - `work check`
 - `work list`
 - Later implementation slices should prefer focused `cargo test -p hemx-lsp`/integration tests, then `cargo check --workspace` or `cargo run -p hemx-xtask -- test` when build integration changes.
 ## Non-goals
 - Do not build a custom editor framework, formatter, Rust type system, selector model, or second `.heml` parser.
 - Do not make VS Code/Cursor/Neovim provider behavior the source of truth; provider glue stays downstream of LSP/build facts.
 - Do not add external publishing/signing flows without explicit authority.
 ## Evidence
 - `hemx-lsp/src/main.rs` already exposes diagnostics, completion, and hover entry points.
 - `docs/editor-support.md` and `docs/diagnostics.md` define the editor/build boundary.
@@ -0,0 +1,44 @@
 ---
 id: NS-0003
 type: northstar
 status: ready
 title: Hemplate highlighting and editor grammar boundary
 refs:
  - docs/editor-support.md
  - docs/hemplate-syntax.md
  - REQUIREMENTS.md
  - README.md
 ---
 ## Objective
 Make `.heml` highlighting predictable in editors by defining the repo-owned highlighting boundary: HTML/tree-sitter remains the base, hemplate overlays cover only the documented syntax facts, and diagnostics/completion stay owned by `hemx-build`/`hemx-lsp`.
 ## Authority
 - `docs/editor-support.md` says `.heml` should keep normal HTML highlighting and layer hemx-specific editor support on top.
 - `docs/hemplate-syntax.md` defines escaped/trusted text, dynamic attributes, control flow, generated hemx targets, and boundaries.
 - `REQUIREMENTS.md` `diagnostics/004` through `diagnostics/008` require optional overlays to share authority with `hemx-build` and avoid a second template language or custom editor framework.
 ## Close when
 - Highlighting ownership is explicit: repo-owned fixtures/queries can cover documented hemplate tokens, while external editor distribution remains a separate slice or blocker.
 - Tree-sitter work is bounded to syntax highlighting/injection facts and never owns diagnostics, completion, formatting, Rust type checking, or template validation.
 - Ready slices distinguish repo-testable grammar/query behavior from editor packaging/publishing work that may require external authority.
 ## Verification
 - `work check`
 - `work list`
 - Later implementation slices should use repo-owned fixture/query tests where available; provider-specific visual/manual checks must name the editor and blocker.
 ## Non-goals
 - Do not create a second `.heml` parser for hemx-build.
 - Do not make highlighting responsible for compiler diagnostics, completion, hover, formatting, or generated Rust facts.
 - Do not publish editor extensions or tree-sitter packages without explicit release authority.
 ## Evidence
 - Current docs already frame `.heml` as HTML first with a small hemplate overlay.
 - No current repo authority grants external package publishing; that is represented as a separate blocked/future slice rather than assumed.
@@ -0,0 +1,41 @@
 ---
 id: SLICE-0001
 type: slice
 status: ready
 parent: NS-0001
 title: Lock fast focused and full verification tiers
 refs:
  - REQUIREMENTS.md
  - README.md
  - AGENTS.md
  - hemx-xtask/src/main.rs
 ---
 ## Objective
 Make the verification ladder executable and documented so contributors know when to run fast crate tests, `html-examples-smoke`, and the full xtask authority wrapper.
 ## Authority
 `README.md`, `AGENTS.md`, and `REQUIREMENTS.md` `test/004`, `test/006`, `test/015`, and `test/016` already define the tier boundary and full local timeout expectation.
 ## Close when
 - README/agent guidance names fast crate tests, focused browser smoke, and full xtask authority separately.
 - `cargo run -p hemx-xtask -- test` remains the full wrapper rather than being bypassed by an undocumented shard.
 - Any shard split is deterministic and documented under the xtask wrapper.
 ## Verification
 - `cargo run -p hemx-xtask -- html-examples-smoke`
 - `cargo run -p hemx-xtask -- test`
 - `redgate health --strict`
 ## Non-goals
 - Do not add a new test harness outside xtask.
 - Do not split the full wrapper unless the measured runtime exceeds the budget.
 ## Evidence
 The current full wrapper has passed locally within the documented 10 minute budget; this slice preserves that authority and makes future splitting explicit only when needed.
@@ -0,0 +1,40 @@
 ---
 id: SLICE-0002
 type: slice
 status: ready
 parent: NS-0001
 title: Keep html_examples browser smoke as runtime confidence proof
 refs:
  - REQUIREMENTS.md
  - hemx-xtask/src/main.rs
  - examples/html_examples/README.md
  - examples/html_examples/src/main.rs
 ---
 ## Objective
 Keep `html-examples-smoke` as the repo-owned browser proof for no-reload dynamic interactions, revealed fallback, interval triggers, and the htmx-equivalent gallery behaviors.
 ## Authority
 `REQUIREMENTS.md` `test/006`, `test/013`, `test/014`, `convention/005`, `convention/014`, and `examples/012` constrain the smoke: no `/tmp` scripts, no navigation/reload fallback, and deterministic browser coverage.
 ## Close when
 - The smoke covers click-to-edit, edit-row, inline validation, active search, delete row, lazy load, click-to-load, infinite/reveal, progress interval, value select, reset input, and revealed fallback without IntersectionObserver.
 - The no-navigation/no-reload guard wraps dynamic interactions.
 - Failures identify the named smoke path.
 ## Verification
 - `cargo test -p hemx-xtask`
 - `cargo run -p hemx-xtask -- html-examples-smoke`
 ## Non-goals
 - Do not add Playwright, Selenium, or a second browser runner without a separate decision.
 - Do not move smoke scripts to `/tmp` or untracked files.
 ## Evidence
 `hemx-xtask/src/main.rs` owns the CDP-driven smoke command and inline smoke scripts.
@@ -0,0 +1,40 @@
 ---
 id: SLICE-0003
 type: slice
 status: ready
 parent: NS-0001
 title: Protect keyed collection regressions with generated-resource assertions
 refs:
  - REQUIREMENTS.md
  - examples/html_examples/src/main.rs
  - hemx-test/src/lib.rs
 ---
 ## Objective
 Make keyed list regressions easy to catch without raw selector or raw effect coupling: tests should assert generated resource behavior for remove, replace, and append paths.
 ## Authority
 `REQUIREMENTS.md` `list/006`, `test/008`, `test/009`, `test/010`, and `test/017` constrain keyed collection behavior and test diagnostics.
 ## Close when
 - Filtered keyed collections are tested for removing filtered-out keys, replacing retained keys, and appending newly visible keys.
 - Assertions use generated resource helpers or `hemx_test` inspection adapters, not raw runtime ids as app-facing API.
 - Failure messages name generated resources where practical.
 ## Verification
 - `cargo test -p hemx-html-examples`
 - `cargo test -p hemx-test --test inspector`
 - `cargo run -p hemx-xtask -- html-examples-smoke`
 ## Non-goals
 - Do not add app authoring APIs for selectors or raw runtime ids.
 - Do not test private runtime payload layout unless the slice changes wire semantics.
 ## Evidence
 The active-search example and `hemx_test` helpers already provide anchors for this regression boundary.
@@ -0,0 +1,40 @@
 ---
 id: SLICE-0004
 type: slice
 status: ready
 parent: NS-0001
 title: Keep requirement and test governance aligned
 refs:
  - REQUIREMENTS.md
  - AGENTS.md
  - redgate
 ---
 ## Objective
 Keep behavior-changing test work tied to checkable requirements without turning redgate cleanup into unrelated product scope.
 ## Authority
 `AGENTS.md` requires reading and updating `REQUIREMENTS.md` when behavior changes, citing relevant `req:` IDs, and running redgate commands when requirements change.
 ## Close when
 - Behavior-changing test slices cite the requirements they constrain.
 - Requirement-only maintenance is separated from behavior implementation.
 - `redgate health --strict` and `redgate lint` are green for the changed scope.
 ## Verification
 - `redgate health --strict`
 - `redgate lint`
 - Relevant behavior test from the implementation slice.
 ## Non-goals
 - Do not add citation-only padding.
 - Do not make redgate adoption or formatting the product payoff.
 ## Evidence
 The repo already uses `REQUIREMENTS.md`, redgate, and `req:` citations as durable governance authority.
@@ -0,0 +1,43 @@
 ---
 id: SLICE-0005
 type: slice
 status: ready
 parent: NS-0002
 title: Prove LSP diagnostics parity with hemx-build
 refs:
  - REQUIREMENTS.md
  - docs/diagnostics.md
  - docs/editor-support.md
  - hemx-lsp/src/main.rs
  - hemx-build/src/lib.rs
 ---
 ## Objective
 Make LSP diagnostics a faithful editor transport for `hemx-build` diagnostics across open, change, save, close, and CLI file checks.
 ## Authority
 `docs/diagnostics.md` and `REQUIREMENTS.md` `diagnostics/004`, `diagnostics/005`, and `check/001` require editor overlays to share compiler authority and preserve useful spans.
 ## Close when
 - A focused LSP test opens an invalid `.heml` document and observes the same diagnostic code/severity/range as the `hemx-lsp diagnostics FILE.heml` path.
 - `didChange` updates diagnostics from in-memory text.
 - `didSave` with and without text uses the documented source of truth.
 - `didClose` clears diagnostics.
 ## Verification
 - `cargo test -p hemx-lsp`
 - `cargo run -p hemx-lsp -- diagnostics <fixture>.heml`
 - `cargo check --workspace` if public LSP/build types change.
 ## Non-goals
 - Do not implement a second `.heml` parser in the LSP.
 - Do not add provider-specific VS Code/Neovim behavior in this slice.
 ## Evidence
 `hemx-lsp/src/main.rs` already has diagnostics CLI and LSP publish paths that can be covered with protocol tests.
@@ -0,0 +1,40 @@
 ---
 id: SLICE-0006
 type: slice
 status: ready
 parent: NS-0002
 title: Complete context-aware hemplate completions
 refs:
  - REQUIREMENTS.md
  - docs/editor-support.md
  - docs/hemplate-syntax.md
  - hemx-lsp/src/main.rs
 ---
 ## Objective
 Make completion useful for the real hemplate surface: directives, dynamic attributes, and `data-hemx-*` facts should complete in context without inventing syntax.
 ## Authority
 `docs/hemplate-syntax.md` defines the public syntax; `docs/editor-support.md` and `REQUIREMENTS.md` `diagnostics/006` require completions to support that surface while remaining subordinate to build validation.
 ## Close when
 - Completion items cover `h-if`, `h-for`, `h-key`, `h-match`, `h-case`, `{+ +}`, `{+= =+}`, `+attr`, and known `data-hemx-*` authoring facts.
 - Tests prove context filters: directive completions in tag attributes, snippet/text completions in text positions, and no irrelevant completions inside quoted Rust expressions.
 - Completion docs/details point to the existing syntax docs rather than new invented rules.
 ## Verification
 - `cargo test -p hemx-lsp`
 - Manual check if needed: request `textDocument/completion` against a fixture through the LSP test harness.
 ## Non-goals
 - Do not add Rust type inference or project-wide symbol completion in this slice.
 - Do not make completion acceptance a build authority.
 ## Evidence
 `hemx-lsp/src/main.rs` already exposes `completionProvider` and `hemplate_completion_items` anchors.
@@ -0,0 +1,39 @@
 ---
 id: SLICE-0007
 type: slice
 status: ready
 parent: NS-0002
 title: Complete hover help for documented hemplate facts
 refs:
  - REQUIREMENTS.md
  - docs/editor-support.md
  - docs/hemplate-syntax.md
  - hemx-lsp/src/main.rs
 ---
 ## Objective
 Make hover explain the real `.heml` facts that contributors see in templates without turning hover into a tutorial or alternative spec.
 ## Authority
 `docs/hemplate-syntax.md` defines the facts; `REQUIREMENTS.md` `diagnostics/007` and `diagnostics/008` constrain hover and editor behavior.
 ## Close when
 - Hover covers escaped/trusted text, dynamic attributes, control-flow directives, generated targets, forms, handles, roots, and keyed slots.
 - Hover content is short and points back to the documented syntax authority.
 - Hover tests assert range-sensitive behavior and no hover for unrelated HTML text where normal editor tooling owns the answer.
 ## Verification
 - `cargo test -p hemx-lsp`
 ## Non-goals
 - Do not duplicate `docs/hemplate-syntax.md` wholesale in source strings.
 - Do not include provider-specific Markdown rendering assumptions.
 ## Evidence
 `hemx-lsp/src/main.rs` already exposes `hoverProvider` and `hemplate_hover` anchors.
@@ -0,0 +1,41 @@
 ---
 id: SLICE-0008
 type: slice
 status: ready
 parent: NS-0002
 title: Surface cross-file facts without replacing build validation
 refs:
  - REQUIREMENTS.md
  - docs/editor-support.md
  - docs/diagnostics.md
  - hemx-build/src/lib.rs
  - hemx-lsp/src/main.rs
 ---
 ## Objective
 Define and prove the handoff between editor-visible template facts and `cargo check`/`hemx-build` completeness checks for template/handler references.
 ## Authority
 `REQUIREMENTS.md` `check/001`, `check/003`, `diagnostics/004`, and `diagnostics/005` require cross-file references visible to build validation to fail at `cargo check` with useful spans, while editor overlays remain optional glue.
 ## Close when
 - A test fixture demonstrates a template/handler reference that editor diagnostics can surface and `cargo check`/build validation also rejects.
 - The LSP path reports useful spans without becoming the global source of truth.
 - Global completeness boundaries remain component-scoped unless mount/tests are needed.
 ## Verification
 - `cargo test -p hemx-lsp`
 - `cargo check --workspace` or a focused compile-fail/build fixture when build validation changes.
 ## Non-goals
 - Do not make the LSP own Rust type checking.
 - Do not create a persistent project index unless a later slice proves it is required.
 ## Evidence
 `docs/diagnostics.md` and `hemx-build` diagnostics define the authority boundary that editor support must reflect.
@@ -0,0 +1,39 @@
 ---
 id: SLICE-0009
 type: slice
 status: ready
 parent: NS-0002
 title: Harden LSP protocol behavior
 refs:
  - hemx-lsp/src/main.rs
  - docs/editor-support.md
  - REQUIREMENTS.md
 ---
 ## Objective
 Make `hemx-lsp` predictable as an LSP server: initialize capabilities, document sync, completion, hover, diagnostics, shutdown, and unknown request errors should have focused protocol tests.
 ## Authority
 `hemx-lsp/src/main.rs` implements the protocol loop; `docs/editor-support.md` names the editor-facing command surface.
 ## Close when
 - Tests cover `initialize`, `didOpen`, `didChange`, `didSave`, `didClose`, `completion`, `hover`, `shutdown`, and unknown requests.
 - The tests assert JSON-RPC framing and response IDs, not just helper functions.
 - The server keeps normal HTML/tree-sitter tooling assumptions and does not add editor-provider policy.
 ## Verification
 - `cargo test -p hemx-lsp`
 - `cargo run -p hemx-lsp -- help`
 ## Non-goals
 - Do not add async runtime or background watchers unless protocol tests prove sync IO is insufficient.
 - Do not publish editor extensions in this slice.
 ## Evidence
 The current LSP loop is small and testable through in-memory readers/writers.
@@ -0,0 +1,39 @@
 ---
 id: SLICE-0010
 type: slice
 status: ready
 parent: NS-0003
 title: Define repo-owned hemplate highlighting boundary
 refs:
  - docs/editor-support.md
  - docs/hemplate-syntax.md
  - REQUIREMENTS.md
 ---
 ## Objective
 Turn "tree-sitter highlighting for hemplate" into a bounded repo-owned contract: HTML stays the base grammar, hemplate overlay tokens are documented, and validation remains with `hemx-build`/`hemx-lsp`.
 ## Authority
 `docs/editor-support.md` says normal HTML/tree-sitter tooling remains in use; `docs/hemplate-syntax.md` names the small overlay; `REQUIREMENTS.md` forbids a second template language or custom editor framework.
 ## Close when
 - A highlighting boundary doc or work artifact lists the token classes the repo owns: escaped/trusted text delimiters, dynamic attribute prefix, `h-*` directives, and `data-hemx-*` facts.
 - It explicitly excludes diagnostics, completion, hover, formatting, Rust expression parsing, and build validation from highlighting authority.
 - It names what can be tested in-repo without editor package publishing.
 ## Verification
 - `work check` for the slice contract now.
 - Later implementation: a repo-owned fixture/query test command, or a manual editor smoke if no automated query runner exists yet.
 ## Non-goals
 - Do not introduce a new parser for `hemx-build`.
 - Do not publish or install editor packages.
 ## Evidence
 The docs already establish `.heml` as HTML plus a small overlay; this slice makes that boundary executable before writing queries.
@@ -0,0 +1,39 @@
 ---
 id: SLICE-0011
 type: slice
 status: ready
 parent: NS-0003
 title: Add hemplate highlighting fixtures and query tests
 refs:
  - docs/hemplate-syntax.md
  - docs/editor-support.md
  - REQUIREMENTS.md
 ---
 ## Objective
 Create repo-owned highlighting fixtures that prove documented hemplate syntax receives stable captures while ordinary HTML remains handled by existing HTML tooling.
 ## Authority
 `docs/hemplate-syntax.md` is the syntax authority; `docs/editor-support.md` says highlighting is HTML first with hemx overlays.
 ## Close when
 - Fixtures cover text insertion, trusted HTML insertion, dynamic attributes, `h-if`, `h-for`, `h-key`, `h-match`, `h-case`, `data-hemx-root`, `data-hemx-slot`, `data-hemx-form`, and `data-hemx-handle`.
 - Tests or golden outputs verify capture names for those tokens.
 - The test path is repo-owned and does not require publishing a VS Code/Cursor/Neovim package.
 ## Verification
 - Preferred future command: a repo-owned tree-sitter/query fixture test, once the crate/tool location is chosen.
 - Until then, manual proof must name the exact editor/query runner and fixture.
 ## Non-goals
 - Do not parse Rust expressions inside `{+ +}` beyond highlighting delimiters/expression region.
 - Do not make highlights responsible for diagnostics or completion.
 ## Evidence
 The fixture list maps directly to the documented syntax surface.
@@ -0,0 +1,38 @@
 ---
 id: SLICE-0012
 type: slice
 status: blocked
 parent: NS-0003
 title: Package editor highlighting integrations
 refs:
  - docs/editor-support.md
  - README.md
 ---
 ## Objective
 Ship `.heml` highlighting into specific editors only after repo-owned syntax/query behavior exists and release authority is explicit.
 ## Authority
 `docs/editor-support.md` names VS Code, Cursor, and Neovim setup, but current repo authority does not grant external marketplace/package publishing from this work-graph mapping goal.
 ## Close when
 - The target editor/provider is named.
 - The package owner, signing/publishing credentials, and release process are explicit.
 - The provider package consumes repo-owned query/fixture facts rather than becoming a separate syntax authority.
 ## Verification
 - Provider-specific install/manual smoke, named by the future implementation slice.
 - Repo-owned query fixture tests from `SLICE-0011` remain green.
 ## Non-goals
 - Do not publish marketplace packages or mutate external editor registries under the current authority.
 - Do not fork syntax behavior per editor.
 ## Evidence
 This is intentionally blocked by missing external release authority, not by an implementation guess.