@ethlete/agent-rules 0.1.0-next.16 → 0.1.0-next.17

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.17
+
+### Minor Changes
+
+- `et update` now leaves tasks to fix code written under the earlier guidance: app styling, URL-bound list state, hand-debounced search, hand-built charts, avatars and progress bars, and the Nx layout.
+- `timetrack resync --replace` re-reads a checkout's agent logs and replaces the samples the store already holds for those sessions, so a parser fix reaches stored days.
+
+### Patch Changes
+
+- The Angular and signals skills cover shared `injectX()` logic, per-row formatting, writing query params and effects that only write a signal; the comment rule says app code rarely has public API.
+- Add the consumer skills `verify-in-app` (drive the served app headlessly with Playwright) and `app-testing` (specs for query, router and overlay code), and link the new query testing docs page from the query skill.
+- The `app-styling` rule and its migration now keep `ViewEncapsulation.None` on app components, as the `require-view-encapsulation-none` lint rule requires, and scope the remaining CSS under the component's host class.
+- Consumer repos get an `app-styling` rule (Tailwind in app templates, 10px rem root) instead of the SDK's component styling rule, and the `query` and `sdk-docs` skills now point to `defineQueryForm` and every component domain.
+- Query skill: bridge a correlated result into RxJS with `executeUntilSettled$`, keeping the Promise form for signal-forms `submit()`.
+- The `list-state-query-form` task binds pagination, page size and a table sort the way that works, and keeps `replaceUrl: true`. The query skill names `observe({ replaceUrl: true })`.
+- The guidance migrations find the call sites they missed in a real app, and generated commands use the repo's package manager.
+- The `app-styling-utilities`, `sdk-components-over-hand-built-ui` and `nx-layout` migration tasks name the real theme utilities, find more call sites, and stop before overriding a repo's own rules or the generated `AGENTS.md` block.
+- Consumer Nx workspaces get an `nx-layout` rule: thin apps, feature code in `libs/domain`, and shared `queries`, `types`, `uikit`, `theme` and `env` libs with `scope:*` tags.
+- The consumer query skill now maps every @ethlete/query capability to its docs page, so agents find APIs like `defineQueryForm` instead of hand-building them.
+- `ethlete-agents` commands run from a subdirectory now use the nearest directory holding `ethlete-agents.config.json` as the repo root, so `check` no longer reports false drift there.
+- The `sdk-docs` skill points consumer agents at the new App setup docs page first: root font size, theme generation and the providers an app needs.
+- `sync` and `check` now name every skill or rule skipped for an unmet `requires` or missing var, and warn when a path var like `themeStylesheet` points at a missing file.
+- `vars.themeStylesheet` may now name a folder of theme files. The `story-styling` skill searches it recursively.
+- `recommendedTs` now uses `ethlete/consistent-type-definitions` instead of `@typescript-eslint/consistent-type-definitions`, so `--fix` no longer turns an interface inside `declare module` or `declare global` (such as the theme-name registry the `@ethlete/core` generators emit) into a type alias that merges into nothing.
+- The `ET100` error now says mutations need `withArgs` too and calls `silenceMissingWithArgsFeatureError` an escape hatch; the query skill recommends `withArgs` for mutations.
+
 ## 0.1.0-next.16
 
 ### Patch Changes

package/README.md

@@ -99,18 +99,19 @@ Prettier rewrites them and `check` then reports drift on every run:
   `.agents/skills/` is the cross-tool baseline) and adds `claude`, `cursor` or `copilot`
   when their directory exists; or list an explicit subset.
 - **`profile`** - `"consumer"` (default) emits `scope: consumer` and `scope: both`
-  content. `"sdk"` emits only `both`; the SDK repo uses it so its own hand-written,
-  authoring-side guides are not overwritten by the consumer-side versions.
+  content. `"sdk"` emits `scope: sdk` and `scope: both`; the SDK repo uses it so its own
+  hand-written, authoring-side guides are not overwritten by the consumer-side versions.
 - **`vars`** - values for the template tokens a guide declares. Defaults live in
   `content/defaults.json`; a guide whose variable has no default and no value is
   skipped with a warning rather than emitted with a dangling placeholder. Some are
   derived from the repo instead of defaulted - the `gitFlow*` ones from the `gitFlow`
-  block, and `commitRuleSource` / `commitValidation` from whether a commitlint config
+  block, `packageRunner` (`yarn`, `pnpm exec`, `bunx` or `npx`) from the root
+  `package.json`'s `packageManager` or the lockfile, and `commitRuleSource` / `commitValidation` from whether a commitlint config
   exists (`commitlint.config.*`, `.commitlintrc*`, or a `commitlint` key in
   `package.json`). Without one, the git-commit guide presents the format as the repo's
   convention and never mentions a `commitlint` run - an agent that goes looking for a
   promised validator and finds nothing reports the discrepancy instead of just
-  committing. Setting either one in `vars` overrides the detection.
+  committing. Setting any derived var in `vars` overrides the detection.
 - **`exclude`** - rule or skill names to skip entirely for every configured agent and
   developer. For example, `"exclude": ["git-flow", "handoff"]` prevents those skills
   from being generated; the next `sync` also removes copies generated previously. Unknown

package/content/rules/app-styling.md

@@ -0,0 +1,47 @@
+---
+name: app-styling
+description: App components are styled with Tailwind utilities in their templates; app CSS stays out of @layer components; the SDK needs a 10px rem root; hardcoded colours are never primary values.
+kind: rule
+scope: consumer
+requires: ['@ethlete/core']
+---
+
+## Styling
+
+Every component in this workspace (views, pages, shells, shared UI in `libs/`) is laid out
+and styled with **Tailwind utility classes in its template**, including the generated
+theme utilities (`bg-et-surface-bg`, `border-et-surface-border`, `text-et-<theme>`). Do not
+invent a BEM class system, and do not write a `.css` file for layout, spacing or
+typography a utility expresses. Every app component sets `encapsulation: ViewEncapsulation.None`,
+as the `require-view-encapsulation-none` lint rule requires. Its CSS is then global, so give the
+component a host class (`host: { class: 'app-player-card' }`) and scope every selector under it,
+the way SDK components scope theirs under their `et-` classes. Never write a bare element or
+unprefixed class selector in a component stylesheet.
+
+Write CSS only for what utilities cannot express. Keep that CSS **unlayered** or in
+`@layer utilities` — never in `@layer components`, and that includes the global stylesheet. SDK component styles are injected into
+`@layer components` at runtime, after your stylesheet, so an app rule in the same layer
+ties on layer and loses on source order.
+
+To change an SDK component's look, set its `--et-*` tokens first (documented per
+component), then use a utility class or unlayered CSS on the element — see "Overriding
+component styles" in the docs site's components overview.
+
+The SDK sizes everything in `rem` on a **10px root**: the app's global stylesheet must set
+`html { font-size: 62.5%; }`. Without it every SDK control renders 1.6× too large. With it,
+`1rem` is `10px`, so the app's own `rem` values stay easy to read.
+
+The 10px root also shrinks every rem-based Tailwind scale to 62.5% of its nominal size (1.6×
+smaller): `p-4` is 10px instead of 16px, and `max-w-3xl` is 480px instead of 768px. Set
+`--spacing: 0.4rem` in the app's `@theme` so the spacing scale keeps its 4px step, as the SDK's
+own Storybook does. Redefine any other rem scale the app uses (`--text-*`, `--container-*`,
+`--radius-*`) the same way, or use px where a size matters. Breakpoints are not affected: a
+media query's `rem` ignores the root font size.
+
+**Never use a hardcoded colour as the primary value.** Backgrounds, text, borders and
+interaction states resolve from the surface and colour theming tokens
+(`--et-surface-*-solid`, `--et-theme-color-*`) or their generated utilities. A static
+fallback inside `var(--token, <fallback>)` is permitted, but not required.
+
+Theme **names** (`brand`, `danger`, `dark-elevated`, …) are registered by this app; the SDK
+ships none. Semantic colours resolve by theme `type` (e.g. `injectErrorTheme()`).

package/content/rules/comments.md

@@ -20,6 +20,8 @@ smaller function, or a type; fix that instead of narrating it.
    limitation) and linking it where a link exists, so the next reader can tell when it may go.
 4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
    exports. One or two sentences. Not internals, not history, not why it is shaped that way.
+   In an application nothing is public API unless it lives in a shared lib other projects
+   import, so this case rarely applies to app code.
 
 Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
 of members, not a summary of the function underneath it.
@@ -43,7 +45,8 @@ years.
   annotation, a factory instead of a literal, a helper moved into its own file. The type, the
   annotation and the import already say what happens.
 - **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
-  Z", "renamed for clarity". Git knows; the next reader does not care.
+  Z", "renamed for clarity", "see ADR-0012". Git and the ADR index know; the next reader does
+  not care.
 - **The same explanation at every call site.** Explain a pattern once where it is defined (the
   helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
 - **Commented-out code.**

package/content/rules/nx-layout.md

@@ -0,0 +1,47 @@
+---
+name: nx-layout
+description: Nx workspace layout - thin apps, feature code in libs grouped by kind, path-mirroring aliases, scope tags.
+kind: rule
+scope: consumer
+requires: ['nx']
+---
+
+## Nx workspace layout
+
+Apps are thin shells. All feature code lives in libs, grouped by kind, not by Nx type:
+
+```text
+apps/<app>/src/app/        app.component.ts, app.config.ts, app.routes.ts only
+libs/
+  domain/<app>/<feature>/  views, components, services, <feature>.routes.ts
+  domain/<app>/shared/     code shared by one app's features (optional)
+  queries/                 query clients and creators, one folder per backend
+  types/                   API models and shared types
+  uikit/                   app-agnostic presentational components
+  theme/                   surface and colour themes
+  env/                     environment.ts, environment.production.ts
+  assets/                  fonts, icons, images
+```
+
+- `app.routes.ts` only lazy-loads domain libs:
+  `loadChildren: () => import('@acme/domain/admin/users').then((m) => m.USERS_ROUTES)`.
+  Each feature lib exports its own `<FEATURE>_ROUTES`.
+- A small app may use one lib per app (`libs/domain/<app>`) with a folder per feature.
+  Never put features, queries, shared UI or theme in the app project.
+- Do not add Nx `feature/ui/data-access/util` folders or `type:*` tags.
+- Every lib has `src/index.ts` and explicit `build` (`@nx/angular:ng-packagr-lite`), `lint`
+  and `test` targets in `project.json`. Keep `plugins: []` in `nx.json`.
+- Alias = path with slashes: `@acme/domain/admin/users`, `@acme/queries`, `@acme/types`,
+  `@acme/uikit`, `@acme/env`. Project name = path with dashes (`domain-admin-users`).
+  Component `prefix` = the repo abbreviation.
+- Tag every project with one `scope:*`: `scope:<app>` for an app and its domain libs,
+  `scope:core` for env and types, plus `scope:queries`, `scope:uikit`, `scope:theme`.
+  `@nx/enforce-module-boundaries` with `enforceBuildableLibDependency: true` lets
+  `scope:<app>` depend on itself and the shared scopes, never on another app.
+- A backend in the same workspace is an app in `apps/` with its libs in
+  `libs/domain/<name>-api`. Ban `@angular/*` in backend scopes and `@nestjs/*` in frontend
+  scopes with `bannedExternalImports`.
+- Environment config lives only in `libs/env`, never hardcoded in a query client.
+
+This is the layout for new workspaces and new code. Do not restructure an existing
+workspace that deviates from it unless the user asks.

package/content/rules/styling.md

@@ -2,7 +2,7 @@
 name: styling
 description: Component CSS is plain CSS in @layer components, and hardcoded colours are never primary values.
 kind: rule
-scope: both
+scope: sdk
 requires: ['@ethlete/core']
 ---
 

package/content/skills/angular-patterns/SKILL.md

@@ -28,6 +28,16 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 <button [disabled]="disabled()"></button>
 ```
 
+- **Per-row formatting belongs in the data, not in a method per row.** Map the rows once
+  in a `computed()` and bind the prepared fields. A pure, module-level formatting function
+  is acceptable too; a component method called for each row in `@for` is not.
+
+```ts
+// ❌ <td>{{ formatDate(row.createdAt) }}</td> - re-runs for every row, every CD cycle
+// ✅
+rows = computed(() => this.items().map((item) => ({ ...item, createdAtLabel: formatDate(item.createdAt) })));
+```
+
 ## Lifecycle
 
 - **Prefer the `constructor`** (runs in the injection context) over `ngOnInit` /
@@ -40,6 +50,10 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
   `createRootProvider` and the `injectX()` helper pattern from `@ethlete/core`
   rather than an `@Injectable` or `@Service`. (Both decorators are lint-banned;
   choosing a function over a service at all is the judgment.)
+- **Repeated component logic → one `injectX()` function.** When two components carry the
+  same signals, effects or subscriptions, extract them into an `injectX()` that runs in the
+  injection context and returns what the components bind. Do not copy the block, and do not
+  reach for a base class.
 - **Directives → plain functions where possible.** With signal APIs, move the core
   logic into a function so it's reusable without applying a directive; keep a
   directive only when a host element genuinely needs it. Avoid common input/output
@@ -47,6 +61,15 @@ DOM/`window`, output naming, class-member + decorator-metadata order, no
 - **Pipes → a `computed()` calling a utility function.** Pipes carry no logic;
   most can be dropped in favour of a `computed`.
 
+## Query params
+
+- **Read** them with the `@ethlete/core` signals: `injectQueryParam(key)`,
+  `injectQueryParams()`. `ActivatedRoute` and `router.url` are lint-banned.
+- **Write** them with `inject(Router).navigate([], { queryParams, queryParamsHandling: 'merge' })`.
+  `merge` keeps the params you do not set; `null` removes a param.
+- **Filter, sort and page state bound to the URL** is a query form: with `@ethlete/query`,
+  use `defineQueryForm` instead of writing the params by hand.
+
 ## Components
 
 - Inline template/styles for small components; external `.html` / `.css` files

package/content/skills/app-testing/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: app-testing
+description: How to unit-test an app built on the Ethlete SDK - views that fetch through @ethlete/query (HttpTestingController and the @ethlete/query/testing helpers), components that open overlays, and views that read the URL with injectQueryParam under provideRouter. Read before writing or fixing a spec for a component, view or service that uses @ethlete/query, @ethlete/core router signals or @ethlete/components overlays.
+kind: skill
+scope: consumer
+requires: ['@ethlete/core']
+vars: [docsBaseUrl]
+---
+
+# Testing an Ethlete app
+
+Specs run in jsdom under `TestBed`. Test through the public API the view uses - mount the
+component, answer its requests, move the URL - and assert on what it renders or exposes. The full
+reference for the query helpers is {%docsBaseUrl%}/query/testing.
+
+## Views that fetch
+
+A client made with `createQueryClient` is provided in root, so a spec provides nothing for it. It
+needs Angular's HTTP testing backend, and answers each request by hand:
+
+```ts
+import { provideHttpClient } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+
+beforeEach(() => {
+  TestBed.configureTestingModule({ providers: [provideHttpClient(), provideHttpClientTesting()] });
+});
+
+afterEach(() => TestBed.inject(HttpTestingController).verify());
+
+it('renders the players', async () => {
+  const http = TestBed.inject(HttpTestingController);
+  const fixture = TestBed.createComponent(PlayersComponent);
+  fixture.detectChanges();
+  TestBed.tick();
+
+  http.expectOne((req) => req.url.includes('/players')).flush({ items: ['Müller'] });
+  await fixture.whenStable();
+
+  expect(fixture.nativeElement.textContent).toContain('Müller');
+});
+```
+
+- A GET query executes once its args resolve, which happens on change detection -
+  `TestBed.tick()` before `expectOne`, and again after `flush` before reading the query's
+  `response()`, `loading()` or `error()`.
+- `req.url` carries the query string, so `expectOne('https://api.example.com/players?search=mul')`
+  matches the full URL. Match with a predicate, as above, when the params are not the point.
+- Fail a request with `flush(body, { status: 422, statusText: 'Unprocessable Entity' })`.
+- Mutations (`POST`, `PUT`, `PATCH`, `DELETE`) never auto-execute - call `.execute({ args })`,
+  then expect the request.
+
+From `@ethlete/query/testing`:
+
+| Export                                                                        | Use                                                                                                                                 |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `expectAndFlush(http, url, body, status?)`                                    | `expectOne(url).flush(body)` in one call.                                                                                           |
+| `expectFlushAndWait(http, url, body, status?)`                                | The same, then `TestBed.tick()`.                                                                                                    |
+| `setupQueryTest(config?)`                                                     | A scratch client, `HttpTestingController`, `createGet` … `createDelete` creators - for testing code that takes a creator or client. |
+| `setupAuthTest({ querySetup })`                                               | A bearer auth provider on that scratch client, with `login()` / `refresh()` helpers that answer the requests.                       |
+| `createFakeQueryPersistenceStore()`                                           | In-memory persistence adapter - jsdom has no IndexedDB.                                                                             |
+| `installFakeBroadcastChannel()`, `installFakeWebLocks()`, `flushMultiTabSync` | Two clients in one spec behave as two tabs.                                                                                         |
+| `createWebSocketTestDouble()`                                                 | A scripted socket.io `io` for `createWebSocketClient({ io })`.                                                                      |
+
+`setupQueryTest` calls `TestBed.configureTestingModule` itself and replaces `ErrorHandler` with a
+no-op (`mockErrorHandler: false` keeps the real one). Call it inside `beforeEach`, and call
+`restoreConsole()` in `afterEach` if the file spies on `console`.
+
+## Views that read the URL
+
+`injectQueryParam`, `injectQueryParams`, `injectPathParam` and the other router signals from
+`@ethlete/core` read the router, so the spec provides one and navigates it:
+
+```ts
+import { provideRouter, Router } from '@angular/router';
+
+TestBed.configureTestingModule({
+  providers: [provideHttpClient(), provideHttpClientTesting(), provideRouter([])],
+});
+
+await TestBed.inject(Router).navigateByUrl('/?search=mul');
+const fixture = TestBed.createComponent(PlayersComponent);
+fixture.detectChanges();
+TestBed.tick();
+
+http.expectOne((req) => req.urlWithParams.includes('search=mul')).flush({ items: [] });
+
+await TestBed.inject(Router).navigateByUrl('/?search=x');
+TestBed.tick();
+http.expectOne((req) => req.urlWithParams.includes('search=x')).flush({ items: [] });
+```
+
+Navigate to change a param - never set the signal or mock the inject function. A view that also
+reads path params needs the real route in the config (`provideRouter([{ path: 'players/:id',
+component: PlayersComponent }])`) and `RouterTestingHarness` from `@angular/router/testing` to
+render it.
+
+## Components that open overlays
+
+An overlay mounts at the end of `document.body`, not in the fixture, and it opens and closes over
+animation frames. Query the document, wait two frames, and close what is left after each test:
+
+```ts
+import { injectOverlayManager } from '@ethlete/components';
+
+const flushFrames = () =>
+  new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+
+afterEach(async () => {
+  TestBed.runInInjectionContext(() => injectOverlayManager())
+    .openOverlays()
+    .forEach((ref) => ref.forceClose());
+  await flushFrames();
+});
+
+it('opens the edit dialog', async () => {
+  const fixture = TestBed.createComponent(PlayerListComponent);
+  fixture.detectChanges();
+
+  fixture.nativeElement.querySelector('button.edit').click();
+  await flushFrames();
+
+  expect(document.querySelector('.player-edit-dialog')).not.toBeNull();
+});
+```
+
+- Count open overlays with `injectOverlayManager().openOverlays().length` (inside
+  `TestBed.runInInjectionContext`).
+- The `OverlayRef` that `createOverlayOpener(...).open()` returns has `componentInstance()`,
+  `close(result)` and `afterClosed()` - enough to test what the opener does with the result.
+- A query-param overlay (`defineQueryParamOverlay`) opens from the URL: provide the router and
+  navigate with the param set, as above.
+- jsdom has no `ResizeObserver`, `IntersectionObserver`, `matchMedia` or `Element.animate`. If a
+  spec throws on one of them, stub it once in the test setup file with an inert class or function,
+  not per spec.
+
+## Before you call it done
+
+A spec for a bug fix must fail without the fix - revert it, run the spec, see it fail, restore it.
+To check the same change in the running app, read {%skill:verify-in-app%}.

package/content/skills/git-flow/SKILL.md

@@ -16,10 +16,10 @@ what gets deployed to a test environment and, once accepted, merged into
 **Never name a branch by hand - `start` does it from the grammar:**
 
 ```bash
-npx ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
-npx ethlete-agents git-flow check                 # is the current branch conforming?
-npx ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
-npx ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
+{%packageRunner%} ethlete-agents git-flow start FIP-2178        # reads the issue, names it, branches off the right base
+{%packageRunner%} ethlete-agents git-flow check                 # is the current branch conforming?
+{%packageRunner%} ethlete-agents git-flow explain <branch>      # what the parser sees, and what it expects
+{%packageRunner%} ethlete-agents git-flow repair <branch>       # rename a non-conforming one, retarget its MRs
 ```
 
 `start` prints its plan (branch, base, MR target) and asks before writing anything; add