gennady 0.8.3 → 0.8.4-draft.2

package/ai/kit/axiom/e2e/ax-cli-role-locators-from-ax-tree.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_ROLE_LOCATORS_FROM_AX_TREE">
+      Every locator used during exploration is derived from the AX tree just observed (`getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, `getByTestId`). CSS classes, ID selectors, and XPath expressions are forbidden as the primary locator strategy — they bind the test to implementation details that have no contract status.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-cli-snapshot-update-gate.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_SNAPSHOT_UPDATE_GATE">
+      `npx playwright test --update-snapshots` (rewriting AX/visual baselines) is a gated action. Allowed without confirmation only for the very FIRST snapshot of a NEW test (no prior baseline existed). For any update to an existing baseline the agent MUST stop, present the old vs new snapshot to the operator, name the cause of the diff (intentional UI change vs unexpected regression), and wait for explicit confirmation.
+
+      Silent `--update-snapshots` on every failure is the single most direct path for an agent to fabricate a green test under e2e.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-cli-trace-for-failure-diagnosis.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_TRACE_FOR_FAILURE_DIAGNOSIS">
+      When a test fails, the primary diagnostic is `playwright test --trace=on` followed by inspecting the trace via `show-trace`. The trace contains DOM snapshots at each step, network requests, console logs, and a timeline — enough to attribute the failure to a real cause instead of guessing.
+
+      «Edit the test until it passes» without trace inspection is forbidden — it routinely mutes real regressions by relaxing the assertion.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-cli-transition-to-authoring.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_TRANSITION_TO_AUTHORING">
+      Exploration is complete only when: AX snapshot of the target region captured; every interactive element located via `getByRole(...)`; observed structure matches intent. At that point the agent transitions to `playwright-e2e.xml` for codification. Committing a test while exploration is still mid-loop produces a test that asserts the wrong contract.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-auth-via-storage-state.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_AUTH_VIA_STORAGE_STATE">
+      Authentication is handled exclusively via `storageState`: a setup project runs the login flow once, writes `storageState.json`, and dependent projects reuse it. Inline login inside every test is forbidden — it slows the suite, couples every test to the login UI, and turns a login regression into a cascading red across the entire suite.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-ax-tree-as-contract.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_AX_TREE_AS_CONTRACT">
+      The accessibility-tree snapshot (`ariaSnapshot()` + `toMatchAriaSnapshot()`) IS the structural contract. It encodes roles, accessible names, and hierarchy — the same surface a screen reader perceives. Textual/structural assertions on the DOM (e.g. `toContainText`) are allowed where AX granularity is insufficient (specific dynamic copy), but they supplement the AX snapshot, not replace it.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-browser-coverage-pragmatic.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_BROWSER_COVERAGE_PRAGMATIC">
+      Default browser coverage is Chromium. Firefox / WebKit projects are added ONLY when multi-browser support is an explicit ticket requirement. Running every test on every browser inflates CI time without proportional contract evidence; per-route multi-browser opt-in is the trade-off.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-file-layout.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_FILE_LAYOUT">
+      Project-wide layout: tests under `e2e/tests/`, fixtures under `e2e/fixtures/`, auth setup under `e2e/auth/`, snapshot baselines under `e2e/__snapshots__/`. One subject per test file; one domain per fixture file. Mixing layouts forces every reader-agent to grep for the convention instead of trusting it.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-file-size-budget.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_FILE_SIZE_BUDGET">
+      Soft target ≤200 lines per test file; hard ceiling 300 lines (code only). Approaching the budget triggers extraction of shared logic into fixtures or helpers; exceeding it triggers a split by scenario family. Past the ceiling, instruction-following degrades and the file becomes a maintenance liability.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-fixture-based-pom.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_FIXTURE_BASED_POM">
+      Page Objects extend Playwright's `test.extend` fixtures — they are NOT standalone classes the test instantiates by hand. Fixture lifecycle (setup per test, teardown after) is the framework's job; bypassing it by `new SomePage(page)` reintroduces the cleanup problem the fixtures solve.
+
+      One fixture file per business domain (e.g. `auth.fixture.ts`, `checkout.fixture.ts`); unrelated domains do NOT merge into one fixture file.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-headless-always.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_HEADLESS_ALWAYS">
+      Test execution is headless. `--headed` is a human-only debugging mode and never appears in committed scripts or CI configuration.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-network-mock-at-route.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_NETWORK_MOCK_AT_ROUTE">
+      External API calls are mocked via `page.route()` / `context.route()` at the network boundary. Mocking at the component level or hand-patching `window.fetch` is forbidden — it bypasses the request flow the production code actually exercises and routinely misses headers, CORS, or retries.
+
+      If the project standardises on a network-mocking harness (MSW, in-house helper), tests reuse it consistently rather than introducing a parallel mocking path per test.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-role-locators-only.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_ROLE_LOCATORS_ONLY">
+      Locator vocabulary is fixed: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, `getByTestId`. CSS selectors (`.class`, `#id`), XPath, and `nth-child` chains are forbidden as primary locators — they bind the test to implementation details with no contract status. `getByTestId` is a last-resort fallback for elements with no semantic role, and it is reserved for stable test IDs the component team owns.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-self-verification-loop.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_SELF_VERIFICATION_LOOP">
+      After authoring: `npx playwright test --project=chromium`. Observe output → fix failures (in component or test) → re-run. Loop continues until green. Submitting a red test without an EXPLICIT blocker note in the ticket is forbidden — silent red turns the suite into noise the next agent must reverse-engineer.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-snapshot-partial-by-default.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_SNAPSHOT_PARTIAL_BY_DEFAULT">
+      AX snapshots are scoped to a NAMED region by default (`page.getByRole('region', { name: '...' }).ariaSnapshot()`). Full-page snapshots are reserved for tests whose contract IS the full page (e.g. a landing-page structure test). Defaulting to full-page snapshots produces brittle baselines that explode on every unrelated nav/sidebar change.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-structure-ax-first.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_STRUCTURE_AX_FIRST">
+      Test structure is fixed:
+      1. Navigate (`page.goto`).
+      2. Capture / assert structure via `toMatchAriaSnapshot` on a scoped region.
+      3. Interact via `getByRole(...)`.
+      4. Assert the delta via another `toMatchAriaSnapshot` (or focused role-based assertion).
+
+      Skipping the first AX assertion turns the test into «click + hope»; without an initial baseline the interaction's delta has nothing to be a delta from.
+    </Axiom>

package/ai/kit/axiom/e2e/ax-e2e-visual-regression-gated.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-e2e.xml -->
+<Axiom id="AX_E2E_VISUAL_REGRESSION_GATED">
+      Visual regression (`toHaveScreenshot()`) is enabled ONLY when the task explicitly requires pixel-level verification. Default contract verification is structural (AX) + behavioural (interaction). Visual regression baselines drift across font rendering, OS chrome, and unrelated CSS, so they belong only on routes that genuinely care about pixels.
+    </Axiom>

package/ai/kit/axiom/error/ax-catch-log-recover.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_CATCH_LOG_RECOVER">
+Catch-Log-Recover is the only pattern in business-logic catch blocks. First `logger.error` with Trace-Prefix and context, then recovery in ONE of two forms depending on the surrounding method's contract:
+- throw-style API → `throw new Error("[Trace-Prefix] msg", { cause })`.
+- Result-style API → `return fail(error)` (per project Result conventions; the `error` carries `{ cause }` via its own constructor).
+
+`logger.error` records the failure with its context at detection time — this is the LDD trace (debug-level escalation lets an agent reconstruct the data path even when stacks are minified or aggregator-truncated). Recovery preserves control flow.
+
+Both forms require both steps. Skipping `logger.error` makes the failure invisible to the trace; skipping recovery swallows it. NEVER do both (log + throw + return fail) — that re-emits and double-logs across boundaries.
+</Axiom>

package/ai/kit/axiom/error/ax-error-chaining-cause.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ERROR_CHAINING_CAUSE">
+Preserve original context via `{ cause }`. Create and rethrow via `new Error("[Trace-Prefix] ...", { cause })`. NEVER transform `cause` — it can be any value. `cause` is a lossless channel for the root cause; any transform breaks the debug chain.
+</Axiom>

package/ai/kit/axiom/error/ax-error-via-class.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ERROR_VIA_CLASS">
+`Error` subclasses are declared via `class` only. Do NOT replace with `type` or `interface`. Only `class` correctly works with `instanceof`, the prototype chain, and the `cause` chain at runtime. A `type` alias for Error gives no runtime check.
+</Axiom>

package/ai/kit/axiom/error/ax-fail-fast-validation.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_FAIL_FAST_VALIDATION">
+Synchronous validation at the start of the method. Validate arguments synchronously and throw domain errors with context. Earlier validation = fewer state mutations before failure and clearer failure cause from the message.
+</Axiom>

package/ai/kit/axiom/error/ax-focused-error-assertions.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_FOCUSED_ERROR_ASSERTIONS">
+Error cases use a focused set: domain error class via `instanceof` AND a stable message fragment via regex match. Do NOT strict-equal a dynamic error message (correlation ids, timestamps) — flaky failures with no diagnostic signal.
+</Axiom>

package/ai/kit/axiom/error/ax-mandatory-try-catch-in-business-logic.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_MANDATORY_TRY_CATCH_IN_BUSINESS_LOGIC">
+Exception handling is mandatory in business logic. Any business method with network/file/process I/O, mutation of external state, or integration with an external system MUST wrap the failure point in `try`/`catch` per `AX_CATCH_LOG_RECOVER`. Missing try/catch on an integration boundary turns any transient failure into an un-traced un-contextualized exception.
+</Axiom>

package/ai/kit/axiom/error/ax-markup-safety.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dbc-audit.directive.xml -->
+<Axiom id="AX_MARKUP_SAFETY">Audit output avoids guidance likely to break XML, Markdown, anchor pairing, or agent patch placement.</Axiom>

package/ai/kit/axiom/error/ax-minimal-error-surface.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_MINIMAL_ERROR_SURFACE">
+Minimal error surface. Handle only reachable errors. Do not defend against states proven impossible by types, preconditions, or invariants. Defense against the impossible is dead code — simulates reliability and obstructs reasoning about real failure paths.
+</Axiom>

package/ai/kit/axiom/error/ax-must-extractor.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_MUST_EXTRACTOR">
+      Extract a Result's value with `must`: `must(result)` returns the data or throws the contained error. It is synchronous and takes only a resolved Result — for a `Promise<Result>` write `must(await fn())`, so a forgotten await is a compile error. Combine with try/catch at the boundary.
+    </Axiom>

package/ai/kit/axiom/error/ax-no-bare-throw-unknown.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_NO_BARE_THROW_UNKNOWN">
+      `throw catchBinding` without wrapping in `TessellError.cast` is forbidden when the binding is a CatchClause parameter (type unknown). Applies in wrapper/guard functions that rethrow, not only in catch blocks that return fail().
+      Detection: scope analysis — ThrowStatement whose argument resolves to a CatchClause parameter, regardless of variable name (cause, err, e, error).
+      No autofix: the fallback message is context-dependent.
+    </Axiom>

package/ai/kit/axiom/error/ax-no-result-iserr-short-circuit.xml

@@ -0,0 +1,5 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_NO_RESULT_ISERR_SHORT_CIRCUIT">
+      `if (isErr(r)) return r` and `if (!isOk(r)) return r` are forbidden. Use `must` + try/catch — that is the whole point of the convention.
+      No autofix: requires restructuring the surrounding function, not a one-line substitution.
+    </Axiom>

package/ai/kit/axiom/error/ax-no-result-object-literal.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_NO_RESULT_OBJECT_LITERAL">
+      Manual `{ ok: true, data: x, error: null }` and `{ ok: false, data: null, error: e }` are forbidden. Always use `success(x)` / `fail(e)`.
+      Rationale: bypasses the contract, breaks silently if Result shape evolves.
+      Autofix: ok===true → success(data_value); ok===false → fail(error_value).
+    </Axiom>

package/ai/kit/axiom/error/ax-no-result-ok-short-circuit.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_NO_RESULT_OK_SHORT_CIRCUIT">
+      `if (!r.ok) return r` and `if (r.ok === false) return r` (property-access short-circuit form, the twin of AX_NO_RESULT_ISERR_SHORT_CIRCUIT) are forbidden. Use `must` + try/catch.
+      Detection: IfStatement whose test is `!r.ok` or `r.ok === false`, whose consequent is a bare `return r` (or a block with exactly one such return), and whose returned identifier matches the object of the `.ok` access.
+      No autofix: requires restructuring the surrounding function, not a one-line substitution.
+    </Axiom>

package/ai/kit/axiom/error/ax-no-result-second-generic.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_NO_RESULT_SECOND_GENERIC">
+      `Result<T, ConcreteError>` is forbidden. No method can guarantee it only throws one error class — library and runtime code can throw anything. Use `Result<T>` only.
+      Exception: when the second arg is a type parameter of the enclosing generic declaration (function / type alias / class) — that is a constraint, not a pinned class. Detection: AST walk up to nearest TSTypeParameterDeclaration; skip if name appears there.
+      Autofix: remove second type argument.
+    </Axiom>

package/ai/kit/axiom/error/ax-result-unwrap-on-success-paths.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_RESULT_UNWRAP_ON_SUCCESS_PATHS">
+If the SUT returns `Result<T>`, use `unwrap()` / `unwrapSync()` on success paths to collapse «check success + extract value» into one call. The assert then focuses solely on the business shape.
+</Axiom>

package/ai/kit/axiom/error/ax-trace-prefixed-errors.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_TRACE_PREFIXED_ERRORS">
+Every error message carries a Trace-Prefix. Format: `[ClassName#methodName]` or `[functionName]`. With cause-chains across several log/error layers, the only reliable way to recover the failure point is an explicit prefix; stack aggregators may truncate.
+</Axiom>

package/ai/kit/axiom/infra/ax-ai-first-scripts-one-shot.xml

@@ -0,0 +1,27 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_AI_FIRST_SCRIPTS_ONE_SHOT">
+  **Every primary npm script MUST be one-shot — returns control deterministically. Watch / persistent / REPL modes live in separate `:watch` / `:dev` scripts.**
+
+  AI agents (and CI runners) invoke scripts and wait for exit. A script defaulting to watch (e.g., `vitest`, `tsc --watch`, `next dev`) hangs the session — output streams forever, no exit code, no continuation. Agent has no way to distinguish «still working» from «ready, waiting for changes». Most common cause of stuck infra-setup tasks.
+
+  | Script | Behavior | Used by |
+  |---|---|---|
+  | `test` | one-shot, exits | agents, CI, smoke tests |
+  | `test:watch` | watch mode, persistent | human dev |
+  | `lint` | one-shot, exits | agents, CI, pre-commit |
+  | `lint:watch` | watch (rare) | human dev |
+  | `build` | one-shot, exits | agents, CI |
+  | `dev` | long-running dev server | human dev only |
+  | `start` | long-running prod server | deployment runtime |
+  | `start:check` | boot, smoke-ping, exit | agents (smoke-test deployment) |
+
+  **Forbidden in `package.json` scripts:**
+  - `"test": "vitest"` (defaults to watch in TTY) — must be `"vitest run"`.
+  - `"test": "jest --watch"` — watch by default; must be `"jest"`.
+  - `"test": "node --test --watch"` — must be `"node --test"`.
+  - Any primary script that doesn't terminate without manual interrupt.
+
+  For `dev`/`start`: inherently long-running; agents MUST NOT invoke directly during task-execution. Need server smoke-test → declare separate `:check` script that boots, pings, exits within timeout.
+
+  Verification: before declaring infra-setup DONE, run each primary script and confirm exit (any code) within reasonable time. Hang >2 minutes without progress = violation.
+</Axiom>

package/ai/kit/axiom/infra/ax-autofix-preferred.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_AUTOFIX_PREFERRED">
+      **A rule with a working `fix` is the preferred shape; goes in at `'error'` without further justification. A rule WITHOUT working `fix` (or with only `suggest`) goes in at `'error'` ONLY with an inline comment immediately above the rule entry explaining why it is here.**
+
+      The comment names: what class of bugs or invariant it catches, and why nothing else (tsc, review, another directive) covers that concern. Plain prose, free format, but specific enough that the next reader can decide whether the rule still earns its place.
+
+      Partial-fix rules (auto-fix some findings, not others) are treated as non-autofix and need the same comment; if partial coverage is unintentional, prefer reporting upstream and disabling locally.
+
+      **`suggest` is NOT autofix.** A rule exposing only `suggest` (alternatives the user must choose between) falls under non-autofix branch. The pipeline never auto-applies any suggestion. Rule offers BOTH `fix` and `suggest` → only `fix` is consumed; `suggest` is ignored. A pipeline picking `suggest` automatically is a non-deterministic rewrite with no audit trail.
+
+      Why: autofix is the path of least friction for both AI and human — green or a ready patch, no debate. A non-autofix rule is acceptable when it catches a class of bugs nothing else catches — but the cost (a finding an agent must reason about) is real and must be paid deliberately. The comment is the audit trail.
+    </Axiom>

package/ai/kit/axiom/infra/ax-binary-severity.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_BINARY_SEVERITY">
+      **Every rule in `eslint.config.ts` has severity `'error'` (or numeric `2`), or it is `'off'`. There is no third state.**
+
+      Severity `'warn'` (`1`) and any informational level are forbidden — including after preset spreads. Forbidden forms anywhere in the resolved config:
+      - `rule: 'warn'`, `rule: ['warn', ...options]`, `rule: 1`, `rule: [1, ...options]`.
+      - Plugin presets that set rules to `'warn'` are normalized after the spread: every `'warn'` entry overridden to either `'error'` or `'off'`.
+
+      Either you live by the rule, or you break it and pay the penalty. A «yellow lane» makes the system unusable: an AI agent running the lint sees green and ships; a human sees a long warning list and skims past. If a check is worth running, its findings are worth fixing now. If they are not worth fixing now, the rule is wrong for this project and should be off.
+    </Axiom>

package/ai/kit/axiom/infra/ax-branch-strategy.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_BRANCH_STRATEGY">
+  Pick one strategy at project init, document in README, enforce via remote branch protection.
+
+  | Strategy | When |
+  |---|---|
+  | `trunk-based` (recommended default) | small teams + strong CI; short-lived branches off `main`, merged within a day |
+  | `github-flow` | long-lived feature branches, PR-driven, no `develop` |
+  | `git-flow` | planned release cadences; `main` + `develop` + `release/*` + `hotfix/*` |
+
+  Default branch name: `main` (not `master`) — both locally and on remote.
+
+  Branch naming: `<type>/<short-description>`, where `type ∈ {feature, fix, chore, docs, refactor, test, perf}`. Lowercase, kebab-case.
+
+  Mixing strategies within one team multiplies merge confusion.
+</Axiom>

package/ai/kit/axiom/infra/ax-commit-convention.xml

@@ -0,0 +1,18 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_COMMIT_CONVENTION">
+  Default: Conventional Commits format `<type>(<scope>): <subject>`. Alternatives acceptable with documented rationale.
+
+  Conventional Commits:
+  - Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`, `build`, `ci`, `style`, `revert`.
+  - Subject: imperative mood, ≤72 chars, no trailing period.
+  - Body (optional): wraps at 100 chars, blank line between subject and body.
+  - Footer: `BREAKING CHANGE: …`, issue refs, sign-off.
+
+  Example: `feat(auth): add OAuth2 PKCE flow for native clients`.
+
+  Acceptable alternatives (Decision Log entry required):
+  - **plain** — no type prefix, just imperative subject.
+  - **DCO sign-off** — `Signed-off-by: Name <email>` mandatory for licensing/legal; compatible with conventional commits.
+
+  Conventional Commits enables auto-changelog, semantic-release, machine-readable history.
+</Axiom>

package/ai/kit/axiom/infra/ax-config-auditable-by-agent.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_CONFIG_AUDITABLE_BY_AGENT">
+      `eslint.config.ts` is structured so an agent can audit it mechanically:
+      - One config object (or explicit array spread) per logical concern (language options, plugins, file overrides), commented with the concern name.
+      - Every `'error'` rule is either trivially autofixable OR carries the explanatory comment (per `AX_AUTOFIX_PREFERRED`).
+      - Every `'off'` after a preset spread carries a one-line reason.
+      - File globs use the project-wide convention; do not invent ad-hoc patterns inside `overrides`.
+
+      The config itself is the source of truth for the lint contract.
+    </Axiom>

package/ai/kit/axiom/infra/ax-custom-plugins-obey-meta-policy.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_CUSTOM_PLUGINS_OBEY_META_POLICY">
+      Project-local ESLint plugins (custom rules) follow the same meta-policy:
+      - Default: ship a working `fix` for every reported finding.
+      - Allowed alternative: ship without `fix` ONLY if the rule is enabled with an explanatory comment, the same way a third-party non-autofix rule would be.
+      - Severity always `'error'`.
+
+      A custom rule shipping only `suggest` is rejected at code review.
+    </Axiom>

package/ai/kit/axiom/infra/ax-dependency-addition-checklist.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_DEPENDENCY_ADDITION_CHECKLIST">
+  Before adding any dependency, verify three things:
+  1. **Node compatibility:** `npm view <pkg> engines` — supports version in `.nvmrc`?
+  2. **Module system compatibility:** package ESM-only / CJS-only / dual? Matches project's `"type"`?
+  3. **Pinning discipline:** dev tool → `--save-exact`; runtime dep → range acceptable.
+
+  Skipping these introduces incompatibilities that surface as cryptic runtime errors, not install errors.
+</Axiom>

package/ai/kit/axiom/infra/ax-exact-pinning-for-tooling.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_EXACT_PINNING_FOR_TOOLING">
+  Dev-tool packages MUST be pinned to exact versions. `npm install --save-exact` for packages affecting the build pipeline.
+
+  A patch update to a build tool can silently change output. Exact pins guarantee the same tool version runs everywhere.
+
+  Rule: runtime deps (published with the package) may use ranges. Dev deps affecting build output MUST be exact.
+
+  Pattern: `"devDependencies": { "vite": "5.2.11" }`, not `"^5.2.0"` or `"~5.2"`.
+</Axiom>

package/ai/kit/axiom/infra/ax-flat-config.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_FLAT_CONFIG">
+      Project uses ESLint flat config (`eslint.config.ts` or `eslint.config.js`). Legacy `.eslintrc*` files are not introduced; pre-existing ones are scheduled for migration.
+
+      `eslint-config-prettier` (flat variant) appended LAST in the config array so it disables stylistic rules that may have leaked in from earlier presets. Mixing flat and legacy creates resolution surprises and makes audit scripts harder to write.
+    </Axiom>

package/ai/kit/axiom/infra/ax-gitignore-baseline.xml

@@ -0,0 +1,22 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_GITIGNORE_BASELINE">
+  `.gitignore` covers three layers.
+
+  **Mandatory** (every project):
+  - `.claude/settings.local.json` (personal Claude Code overrides; team-shared `.claude/settings.json` IS tracked).
+  - `.env`, `.env.local`, `.env.*.local` (secrets; only `.env.example` with placeholders is tracked).
+  - OS artifacts: `.DS_Store`, `Thumbs.db`, `desktop.ini`.
+  - Editor caches: `.idea/`, `*.swp`, `.vscode/` (or selectively).
+  - Coverage: `coverage/`, `*.lcov`, `.nyc_output/`.
+  - Logs: `*.log`, `npm-debug.log*`, `yarn-error.log`, etc.
+
+  **Tool-derived** (per chosen stack from infrastructure scope discovery):
+  - Node: `node_modules/`, `dist/`, `.next/`, `.nuxt/`, `.cache/`.
+  - Python: `__pycache__/`, `*.pyc`, `.venv/`, `.pytest_cache/`, `.ruff_cache/`.
+  - Go: `vendor/` (if not committed by policy), build artifacts.
+  - Rust: `target/`.
+
+  **Environment-specific:** developer-team decision (e.g., `scripts/local/`).
+
+  Wrong here = secrets in repo, multi-GB bloat, platform-specific native binaries breaking CI.
+</Axiom>

package/ai/kit/axiom/infra/ax-history-policy.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_HISTORY_POLICY">
+  Linear history via rebase or squash-merge for PRs. Force-push forbidden on shared branches.
+
+  - **Shared** (force-push FORBIDDEN): `main`, `develop`, `release/*`, any branch with active PRs from others.
+  - **Personal** (force-push allowed): your own `feature/*`, `fix/*` until merged.
+
+  Merge strategies:
+  - `squash-merge` — feature branch becomes single commit on main. Simple history; loses commit granularity.
+  - `rebase-and-merge` — feature commits rebased onto main, no merge commit. Preserves granularity; requires clean local history.
+  - `merge commit` — discouraged unless branch shape must be preserved (e.g., release branches).
+
+  Hooks bypass: `--no-verify` is FORBIDDEN unless operator explicitly authorizes; if used, the bypass MUST be documented in commit body.
+
+  Shared-branch force-push silently rewrites history collaborators have already pulled. Recovery is manual and error-prone.
+</Axiom>

package/ai/kit/axiom/infra/ax-hooks-integration.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_HOOKS_INTEGRATION">
+  Hooks fire on every commit/push. Required hooks: `pre-commit` (lint + typecheck on staged, <5s), `commit-msg` (conventional-commits validator), `pre-push` (full test suite). Optional: `prepare-commit-msg` (prepend issue ID), `post-merge` (reinstall if lock changed). Hook config committed to repo; one onboarding command registers them (e.g. `lefthook install`).
+</Axiom>

package/ai/kit/axiom/infra/ax-infra-base-bootstrap.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/sdd/setup.directive.xml -->
+<Axiom id="AX_INFRA_BASE_BOOTSTRAP">
+  If the operator declares basic tooling (package manager, type-checker, linter) in intake, the `root` flow materializes a minimal `specs/infra-base/infra-base.spec.md` with scope-type=infrastructure: Vision (one sentence) + Tool Stack (table with tool names only, no Decision Log yet). The full Decision Log appears when the operator runs the `infra` flow on infra-base.
+
+  The minimal bootstrap intentionally bypasses the full `infra` flow — it only locks the tool choice without the Design Variants ritual.
+</Axiom>

package/ai/kit/axiom/infra/ax-infrastructure-flow.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_INFRASTRUCTURE_FLOW">
+      For scope-type=infrastructure:
+
+      **Tool categories — two classes.** Mandatory: vcs, package-management, git-hooks. Optional: type-check, linting, formatting, test-unit, test-e2e, test-ui, bundler, ci, monorepo-tool, docs. The agent proposes a subset from intent. Mandatory categories cannot be dropped.
+
+      **vcs is always mandatory.** Resolves to `ai/directives/infra/git-setup.xml`.
+
+      **Per tool category: 2–3 candidates with trade-offs.** Operator picks → Mandatory Rationale Pull → Decision Log entry. No tool may be locked without a Decision Log entry.
+
+      **Tool interaction check.** After every tool is chosen, verify compatibility (linter vs formatter, test runner vs type-check, CI vs package manager).
+
+      **Effective rules derived from tools.** After tool stack is finalized, look up each chosen tool in `ai/directives/knowledge.xml` `<Rules>` section: find every rule whose `<Triggers>` match the tool name or its config artefacts. Record matched rule `<File>` paths in spec Effective Rules. Missing-rule handling: governed by `AX_SCOPE_RULES_DECLARATION` (in-session operator pick — skip / research-and-author / defer).
+
+      **Dev workflow example is required.** The spec includes a Developer Workflow Example (shell-script shape) before final approval.
+    </Axiom>

package/ai/kit/axiom/infra/ax-lfs-submodules.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/infra/git-setup.xml -->
+<Axiom id="AX_LFS_SUBMODULES">
+  LFS for large binaries. Submodules discouraged.
+
+  **Git LFS** — required when tracking binary files >100MB (GitHub hard limit; other hosts vary). Configure `.gitattributes`: `*.psd filter=lfs diff=lfs merge=lfs -text`. LFS adds infrastructure cost (storage, bandwidth quota) — use only when binaries are necessary.
+
+  **Submodules** — discouraged in favor of monorepo or package dependencies. If unavoidable: pin to specific commit (not branch); document in README why; expect fragile workflow (`git submodule update --init --recursive` after every checkout).
+</Axiom>

package/ai/kit/axiom/infra/ax-lint-run-is-mechanical.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_LINT_RUN_IS_MECHANICAL">
+      **The lint pipeline is exactly one command:** `eslint --fix .` (or the project wrapper). A clean run = exits with code 0. Because every rule is `'error'`, exit 0 means zero findings.
+
+      For autofix-capable rules `--fix` resolves findings silently. For motivated non-autofix rules a remaining finding is hard failure — the agent MUST resolve it by editing code (with the explanatory comment as guidance), never by adding a disable comment.
+
+      Forbidden as normal workflow: running `eslint` without `--fix` and treating the report as a TODO list. The `--fix` form is the canonical entry point.
+    </Axiom>

package/ai/kit/axiom/infra/ax-lock-file-discipline.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_LOCK_FILE_DISCIPLINE">
+  `package-lock.json` always committed. `node_modules/` never committed.
+
+  `.nvmrc` + `package.json` + `package-lock.json` is the **reproducibility triad**. Without lock file, transitive deps re-resolve on every `npm install` → environment drift.
+
+  Usage split: `npm install` locally (may update lock when `package.json` changes); `npm ci` in any automated context (reads lock as law, never updates).
+
+  `.gitignore` MUST contain: `node_modules/`, `dist/`.
+</Axiom>

package/ai/kit/axiom/infra/ax-module-system-explicit.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_MODULE_SYSTEM_EXPLICIT">
+  Module system declared once and never mixed. Mixing `import` and `require` in the same project causes non-deterministic resolution and conditional-exports mismatches. Choose at init; set `"type": "module"` (ESM) or omit/`"commonjs"` (CJS) in `package.json`. Do NOT add `.mjs`/`.cjs` files without an explicit dual-package strategy.
+</Axiom>

package/ai/kit/axiom/infra/ax-no-disable-comments-by-agent.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_NO_DISABLE_COMMENTS_BY_AGENT">
+      **Execution-agent MUST NOT add `eslint-disable`, `eslint-disable-next-line`, `eslint-disable-line`, or file-level disable directives to source code.**
+
+      Rule fires on agent's code → failure mode:
+      1. **Default:** fix the code. If the rule has autofix, `--fix` already did it; if not, the rule is non-autofix and the explanatory comment in config tells the agent how to fix manually.
+      2. Rule genuinely wrong for this codebase → STOP, surface to operator, propose config change, wait for explicit confirmation (`AX_RULE_CHANGE_REQUIRES_OPERATOR_CONFIRM`).
+
+      Existing `eslint-disable` comments in the codebase are out of scope for the agent unless operator explicitly asks them to be revisited; they are NOT an excuse to add new ones.
+
+      Allowed forms (only):
+      - operator-authored disables paired with inline `--` justification naming the rule and reason (e.g., `// eslint-disable-next-line @typescript-eslint/no-explicit-any -- vendor SDK type, see issue #1234`),
+      - file-level disables for generated files (typically excluded from the lint glob entirely; the disable is a belt-and-braces fallback).
+
+      A `disable` comment turns a deterministic gate into per-file negotiation. For an AI agent, it is the path of least resistance to make red turn green without solving anything.
+    </Axiom>

package/ai/kit/axiom/infra/ax-non-autofix-prefer-delegation.xml

@@ -0,0 +1,17 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_NON_AUTOFIX_PREFER_DELEGATION">
+      Before enabling a non-autofix ESLint rule, check whether the same concern is already owned by another channel; prefer the channel.
+
+      Routing table — when these channels cover the concern, the lint rule is `'off'`:
+      | Concern | Owned by |
+      |---|---|
+      | Type-aware checks (`no-unused-vars`, `no-undef`, `consistent-return`, `no-implicit-globals`, etc.) | `tsc --noEmit` under strict |
+      | Structural / size / complexity (`complexity`, `max-lines`, `max-lines-per-function`, `max-depth`, `max-params`) | architecture/testing directives (e.g., `AX_TEST_FILE_SIZE_BUDGET` in `testing/vitest-rules`) |
+      | Design / naming / domain conventions (`no-magic-numbers`, `id-length`, `naming-convention`) | coding directive + operator code review |
+      | Formatting | project's single formatter (`AX_PRETTIER_OWNS_FORMATTING`) |
+      | Security / dependency vulnerabilities | SCA tools (`npm audit`, dependabot, dedicated scanners) |
+
+      A non-autofix lint rule is enabled only when its concern is genuinely NOT covered by any of the above — and the explanatory comment names that gap explicitly.
+
+      Each channel has its own diagnostic model and remediation flow. Duplicating in lint produces two reports for the same problem with different exit codes — noise that erodes trust.
+    </Axiom>

package/ai/kit/axiom/infra/ax-npm-agent-sandbox-registry.xml

@@ -0,0 +1,28 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_NPM_AGENT_SANDBOX_REGISTRY">
+  **Sandboxed agents force npm to use the public registry via inline POSIX env-prefix on every invocation. This bypasses any corporate `~/.npmrc` config that the sandbox cannot reach.**
+
+  The problem: operator's `~/.npmrc` typically points at a corporate registry/proxy reachable only from inside corp network. A sandboxed agent doesn't have access → `npm install` hangs on `ENOTFOUND` / `EAI_AGAIN` or fails.
+
+  **Solution — force public registry per command:**
+  ```bash
+  npm_config_registry=https://registry.npmjs.org/ npm install
+  npm_config_registry=https://registry.npmjs.org/ npm view <pkg>
+  npm_config_registry=https://registry.npmjs.org/ npm ci
+  ```
+
+  Why inline prefix:
+  - Bypasses corp `~/.npmrc` without modifying it (operator's local setup intact).
+  - No persistent state in shell env — nothing leaks between commands.
+  - Self-documenting in logs — operator sees exactly which registry was used.
+  - Sandbox-friendly — no dependency on inherited env from launch context.
+
+  Mechanism: npm config priority — CLI flags > `npm_config_*` env vars > project `.npmrc` > `~/.npmrc` > `/etc/npmrc` > defaults. POSIX `VAR=value command` makes the variable visible to the spawned process only.
+
+  **When corp registry IS required** (project legitimately depends on private corp packages):
+  - Explicit deviation, declared at infrastructure scope discovery time, recorded in Decision Log.
+  - Agent halts with `[!] BLOCKED` per `AX_BLOCKER_ESCALATION`; operator handles install in their full-network shell, OR explicit network-access grant for the sandbox.
+  - Auth for corp registry is out of scope — environment concern, not agent's responsibility.
+
+  **Forbidden:** `npm install` without env-prefix in sandbox (routes through corp `~/.npmrc`, hangs); modifying operator's `~/.npmrc` (breaks operator's other work); committing project `.npmrc` with corp registry URL; silent failure / partial install when registry unreachable (operator must see explicit error).
+</Axiom>

package/ai/kit/axiom/infra/ax-presets-passed-through-the-gate.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_PRESETS_PASSED_THROUGH_THE_GATE">
+      Importing a third-party preset (`@typescript-eslint/recommended`, `unicorn/recommended`, framework configs) does NOT bypass meta-principles. After the spread:
+      - Every rule set to `'warn'` overridden to `'error'` (kept on, with motivation if non-autofix) or `'off'` (with one-line reason). No `'warn'` survives.
+      - Every non-autofix rule enabled by preset is either kept with explicit explanatory comment, or turned off with one-line reason citing the channel.
+
+      Presets are a frequent backdoor for warnings and undocumented non-autofix rules. Treating them as opaque blobs would defeat both meta-principles.
+    </Axiom>

package/ai/kit/axiom/infra/ax-prettier-owns-formatting.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/infra/eslint-setup.xml -->
+<Axiom id="AX_PRETTIER_OWNS_FORMATTING">
+      **Formatting (whitespace, quotes, semicolons, line width, trailing commas, JSX wrapping, import-statement layout when purely stylistic) is owned by ONE dedicated formatter — Prettier by default — and NEVER enforced by ESLint stylistic rules.**
+
+      ESLint stylistic rules (`indent`, `quotes`, `semi`, `comma-dangle`, `max-len`, `space-*`, `arrow-spacing`, `keyword-spacing`, etc.) explicitly disabled in `eslint.config.ts` via `eslint-config-prettier` (flat-config equivalent), appended LAST in the config array so it overrides any rule that drifted in from a preset.
+
+      Formatter pipeline runs BEFORE `eslint --fix`: `prettier --write .` then `eslint --fix .`. Both must exit 0.
+
+      The full mechanical quality pass is a fixed two-step sequence exposed as ONE script (`npm run lint:fix` or equivalent) so agents and humans run the same command. Pre-commit hook runs the same script on staged files; CI runs the read-only variant (`prettier --check . && eslint .`) and fails on any drift.
+
+      Choice of formatter is an architecture decision: Prettier recommended; alternatives (Biome, dprint) acceptable IF the project picks ONE. Two formatters or formatting rules duplicated between ESLint and the formatter = forbidden.
+    </Axiom>