okstra 0.50.0 → 0.51.0

package/runtime/skills/okstra-coding-preflight/architecture/hexagonal.md

@@ -0,0 +1,116 @@
+# Hexagonal Architecture (Ports & Adapters) Overlay
+
+Load this **in addition to** the matching language reference when the project follows ports-and-adapters. Detection signals:
+
+- A `domain/` (or `domains/`, `core/`) folder holding entities and value objects.
+- A `ports/` folder, files matching `*.port.*`, or `abstract class` / `interface` files declared at a domain boundary.
+- An `adapters/` (or `infrastructure/`) folder holding implementations of those ports.
+- Build config / framework that names the pattern explicitly (e.g., NestJS module split into `domain` / `application` / `infrastructure`).
+
+If unsure, ask the user once: *"Does this project use ports-and-adapters? What folder is the domain in?"* — and record the answer in one line so subsequent edits don't re-discover it.
+
+These rules are language-agnostic. The examples use TypeScript/Java-ish syntax; translate to Rust traits, Kotlin interfaces, etc., as needed.
+
+---
+
+## Rule H1 — Ports stay thin
+
+A port is the interface (or abstract class) at the domain/application boundary. The port declares **shape**, not behavior.
+
+A port file's method body — or the interface contract itself — must **not** contain:
+
+- `if` statements that branch on domain state.
+- Validation that throws or returns errors based on input shape.
+- Filtering (`.filter(...)`) over domain collections.
+- Business calculations (math on amounts, date arithmetic that expresses a rule, etc.).
+
+If the port file's method body does any of the above, the logic belongs in the domain (an invariant on the entity, a domain service) — or in the adapter if it's truly I/O-shaped.
+
+Violations:
+
+```ts
+// bad: validation in a port body
+abstract class UserRepository {
+  async save(user: User) {
+    if (!user.email) throw new Error('email required'); // rule check in port
+    return this.persist(user);
+  }
+}
+
+// bad: filtering in a port
+abstract class OrderRepository {
+  async findPending(orders: Order[]) {
+    return orders.filter(o => o.status === 'pending'); // domain rule in port
+  }
+}
+```
+
+Not a violation:
+
+- A pure interface with no method bodies.
+- An abstract method with no implementation.
+- A port file that *imports* domain objects (that's the correct pattern).
+
+---
+
+## Rule H2 — Adapters do I/O, not business logic
+
+Same principle as H1, on the adapter side. The adapter's job is to implement **just** the I/O — a SQL query, an HTTP call, a filesystem read. It is **not** the place to filter by domain state, branch on domain values, or compute business answers.
+
+Smells in adapter methods:
+
+- A `.filter(x => x.status === 'active')` predicate over domain state, *after fetching rows*.
+- An `if` that rejects results based on a domain rule (*"skip if expired"*, *"exclude shared items"*).
+- A method whose name encodes a business rule — `findValid*` / `findActive* `/ `findEligible*`. The adapter should fetch *things*; the caller (or the query itself) should apply the rule.
+- Multiple joins and conditions assembled specifically to satisfy a compound domain rule — the adapter is answering a business question rather than offering a primitive fetch.
+
+Judgment: an adapter **can** push filtering into SQL (`WHERE status = 'active'`) — that's still I/O-shaped. The smell is when:
+
+- The filtering is *application code after the fetch*, or
+- The method name itself encodes a domain rule that a reader cannot tell from the name alone.
+
+A domain-flavored method name (`findValid*` / `findActive*` / `findEligible*`) is not automatically a violation. Accept it when **either** holds:
+
+- The query body is still simple — a single `WHERE` clause on an obvious column, no compound predicate.
+- Moving the predicate out would force an N+1 (the caller would have to fetch all rows and round-trip per row to decide which are valid).
+
+Reject it when the query is complex enough that a reader can't tell what "valid"/"active"/"eligible" means without reverse-engineering the SQL. At that point the rule really is hiding in infrastructure — move the predicate to the domain and rename the adapter to `findAll` / `findByX`.
+
+Not a smell:
+
+- Simple `WHERE` clauses for *data-shape* reasons (`WHERE user_id = ?`) — that's scoping the fetch, not a business rule.
+- Pagination, ordering, basic projection.
+- Mapping raw rows to domain objects — that's the adapter's translation job.
+
+Why it matters: when adapters hold business rules, the rules become invisible from the domain. A reviewer reading the domain sees a clean method; the rule is hidden two layers down in a repository. Changes to the rule require editing infrastructure code. Tests of the rule are forced through I/O. The whole point of ports-and-adapters collapses.
+
+---
+
+## Rule H3 — Domain objects live in the domain folder
+
+Entities, value objects, domain types / enums, and domain errors must be declared under the project's `domain/` folder (or whatever this repo calls it). They must **not** be declared inside a port file or an adapter file.
+
+Violations:
+
+- `class Order { ... }` declared in `order.port.ts`.
+- `type OrderStatus = 'pending' | 'shipped'` declared inside `order.repository.adapter.ts`.
+- `class OrderNotFoundError extends Error {}` declared in a port file but never defined in `domain/`.
+- An interface representing a domain concept (not a port contract) declared outside `domain/`.
+
+Not a violation:
+
+- Domain objects *imported* into a port or adapter file — that's the correct pattern.
+- DTOs (data-transfer types used only by an adapter for wire shape) living next to the adapter.
+- Utility types used only by an adapter's implementation.
+
+The test: **is this type/class a thing the business talks about, or is it plumbing?** Business things belong in `domain/`. Plumbing can live near the plumbing.
+
+---
+
+## Quick checklist before declaring a port/adapter change complete
+
+- [ ] No `if` / `.filter` / validation / business math inside any port body.
+- [ ] Adapter methods are I/O only — any post-fetch JS filtering moved into the query or back to the caller.
+- [ ] Adapter method names are neutral (`findAll`, `findByUserId`) unless the domain-flavored name passes the H2 judgment test.
+- [ ] Every entity, value object, domain enum, and domain error is declared under `domain/`.
+- [ ] Port files only declare shape and `import` domain types — they don't *define* them.

package/runtime/skills/okstra-coding-preflight/clean-code.md

@@ -0,0 +1,254 @@
+# Clean Code Principles (language-agnostic)
+
+Apply these on every change. They override personal taste. They do **not** override project-local rules.
+
+## DRY — Don't Repeat Yourself
+
+A second copy of the same logic is a signal to extract. Two callers of the same algorithm should call the same function.
+
+Bad:
+```javascript
+let total = 0;
+for (let i = 0; i < prices.length; i++) total += prices[i];
+// later, elsewhere:
+let t = 0;
+for (let i = 0; i < prices.length; i++) t += prices[i];
+```
+
+Good:
+```javascript
+const sum = (arr) => arr.reduce((acc, x) => acc + x, 0);
+```
+
+Caveat: do not extract until the duplication is real (rule of three). Premature abstraction is also a code smell.
+
+## KISS — Keep It Simple
+
+The simplest solution that meets the requirement wins. Cleverness has a maintenance cost.
+
+Bad:
+```javascript
+if (data !== null || data !== undefined || data !== '') { ... }
+```
+
+Good:
+```javascript
+if (data) { ... }
+```
+
+## SOLID
+
+- **S**ingle Responsibility — one reason to change per class / module.
+- **O**pen/Closed — open for extension, closed for modification. Prefer composition.
+- **L**iskov Substitution — a subtype must honour the parent's contract.
+- **I**nterface Segregation — many small interfaces beat one fat one.
+- **D**ependency Inversion — depend on abstractions, not concrete implementations.
+
+Bad (SRP):
+```python
+class User:
+    def save(self): ...
+    def send_email(self, msg): ...
+```
+
+Good (SRP):
+```python
+class UserRepository:
+    def save(self, user): ...
+
+class EmailService:
+    def send(self, user, msg): ...
+```
+
+## YAGNI — You Aren't Gonna Need It
+
+Implement what is required **now**. Do not add knobs, options, hooks, or layers for a hypothetical future caller.
+
+Bad:
+```javascript
+function calculator(a, b, op) {
+  switch (op) {
+    case 'add': return a + b;
+    case 'multiply': return a * b; // not asked for
+    case 'divide': return a / b;   // not asked for
+  }
+}
+```
+
+Good:
+```javascript
+const add = (a, b) => a + b;
+```
+
+## Meaningful naming
+
+Names reveal intent. `d` and `crtUsrAcct()` are bugs; `elapsedTimeInDays` and `createUserAccount()` are documentation.
+
+### Names must be truthful
+
+The name must describe what the function actually does. Misleading names break reader expectations and survive renames.
+
+Flag and rename:
+
+- `get*` / `fetch*` / `find*` that also mutate state, throw, or write logs / audits.
+- `is*` / `has*` / `can*` that throw instead of returning a boolean.
+- `find*` that *creates* the entity when missing → `findOrCreate*` or `ensure*`.
+- Names that describe the implementation, not the intent: `loopOverUsers` → `notifyActiveUsers`, `runQuery` → `listOverdueInvoices`.
+- Names that say the opposite of what they do under some branch: `enableFoo` that disables when a flag is off, with no hint in the name.
+
+### Names must stand alone
+
+The test: if the name appeared in a stacktrace, an autocomplete list, or a grep result, would the reader know what it does without opening the file? If not, add specificity.
+
+- Names missing the noun: `createPending()` → `createPendingInstallation()`. The verb is fine; the object is missing.
+- Generic verbs with no information: `handle`, `process`, `execute`, `doStuff`, `manage`. If the function deletes-then-inserts, name it `replace`, not `update`.
+- Constants that will collide with siblings later: `BUCKET` → `FONTS_BUCKET`, `TIMEOUT` → `HTTP_READ_TIMEOUT_MS`, `URL` → `AUTH_SERVICE_URL`.
+- Repository / port methods named after the rule they enforce, not the data they fetch: `findValid*` / `findActive*` / `findEligible*` — the adjective encodes a business rule the caller can't inspect from the name. Prefer `findDesktopLibrariesForUser(userId)` + a domain predicate applied by the caller.
+
+This rule applies most strongly to **names crossing module boundaries**: public methods, exported constants, port methods. Private helpers in a tight local scope get more slack.
+
+## Functions do one thing
+
+If the name contains "and", or you must scroll to read it, split it.
+
+Bad:
+```javascript
+function handleData() {
+  fetchData();
+  processData();
+  displayData();
+}
+```
+
+Good: each step is its own function with a clear name and signature.
+
+### Plain-English summary test
+
+For every function you add or meaningfully modify, ask:
+
+> Can I summarize what this function does, line by line, as a short English sentence per line — and does the resulting summary read as prose?
+
+If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract.
+
+### Also flag and split
+
+- Nested conditionals 3+ levels deep — flatten with early returns or named predicates.
+- Mixed levels of abstraction — a high-level orchestrator suddenly doing string parsing, date arithmetic, or SQL assembly inline.
+- A reader has to track 5+ anonymous temporary values to understand the return.
+- A long `.map().filter().reduce()` chain where each stage does non-obvious work and no stage has a name.
+- Boolean expressions long enough that intent is buried — `if (a && b && !c && (d || e.f > 0) && ...)` without a named predicate.
+- A function that orchestrates 4+ distinct logical phases inline (*fetch → resolve → branch → persist → publish*), each more than a line or two. Even without deep nesting, that's enough work to warrant named sub-methods.
+
+### 50-line cap
+
+A single function/method body must stay within **50 lines**, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps).
+
+Crossing the cap is an extraction signal, not a style nit. Before declaring a function complete, count effective body lines; if over 50, split, or surface the violation and confirm with the user before continuing.
+
+### What's fine
+
+- Functions that read as a straight sequence of clear, already-named steps (each line is an English sentence).
+- Short functions (< ~10 lines) regardless of shape.
+- Idiomatic framework patterns used clearly (a 30-line controller method obviously doing its job).
+- Guard clauses at the top — they *help* readability, they don't count against you.
+
+## Testing discipline
+
+These principles apply to every test file regardless of language or framework. The mechanical detection patterns (which mock library, which spy API) are in each `languages/*.md` Tests section.
+
+### No self-mocking
+
+A unit test for class `Foo` must **not** stub, spy on, or replace methods on the instance of `Foo` being tested. Mocking injected collaborators (other services, repositories, adapters, ports, the clock) is fine and expected.
+
+Why it matters: when you mock a method on the subject under test (SUT), the test no longer verifies that method's behavior — it verifies that *some* version of the class (the one you wired up) calls the mocked method. If someone deletes the real implementation, the test still passes. The test has become a proof of its own shape.
+
+Bad (pseudo, language-agnostic):
+```
+sut = new Foo(deps)
+mock(sut.calculateTotal).returns(100)   // mocking the SUT's own method
+result = sut.checkout()
+assert result.total == 100              // proves wiring, not logic
+```
+
+Good:
+```
+sut = new Foo(deps)                     // real Foo, real calculateTotal
+mock(deps.payment.charge).returns(ok)   // mock the collaborator at the boundary
+result = sut.checkout()
+assert result.total == expectedTotal    // proves the logic
+```
+
+### Behavioral, not implementation tests
+
+Assertions should be about **outcomes** — return values, thrown errors, persisted state, published events, calls made to genuine external boundaries. They should **not** be about *how* the work was done internally — which private helper was called, in what order.
+
+Smells:
+
+- `expect(spy).toHaveBeenCalledWith(...)` as the *only* or *primary* assertion, when the spy is on an internal helper or a pure collaborator with no side effects.
+- Tests that would break if you renamed a private method without changing behavior.
+- Assertions on private methods reached via reflection, cast-to-any, or bracket access — the issue is *reaching into privates*, not the language escape hatch itself.
+- A test file where most assertions are on spies rather than on results.
+
+Legitimately behavioral (these are fine):
+
+- `expect(mailerSpy).toHaveBeenCalledWith(...)` — sending mail *is* the behavior.
+- `expect(paymentGateway.charge).toHaveBeenCalledWith(...)` — charging a card *is* the behavior.
+- `expect(orderRepo.save).toHaveBeenCalledWith(...)` in an application-service test — producing the right save call *is* the point of the service.
+
+The judgment call: is the mocked thing an **outcome boundary** (port, external service, side-effecting adapter) or an **internal helper**? Asserting on boundaries is behavioral; asserting on helpers is implementation-coupled.
+
+## No magic numbers
+
+Replace hardcoded values with named constants.
+
+Bad: `if (age > 18)`
+Good: `const LEGAL_AGE = 18; if (age > LEGAL_AGE)`
+
+## Limit nesting depth
+
+Flatten with early returns / guard clauses. If you reach four nested blocks, refactor.
+
+Bad:
+```javascript
+function process(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasPermission) {
+        // ...
+      }
+    }
+  }
+}
+```
+
+Good:
+```javascript
+function process(user) {
+  if (!user) return;
+  if (!user.isActive) return;
+  if (!user.hasPermission) return;
+  // ...
+}
+```
+
+## Comments explain *why*, not *what*
+
+The code already says **what**. Comments record the hidden constraint, the bug being worked around, the surprising tradeoff. Never narrate the next line.
+
+Bad:
+```javascript
+// increment i
+i++;
+```
+
+Good:
+```javascript
+// User may be soft-deleted; invalidate cache so stale reads vanish.
+cache.invalidate(user.id);
+```
+
+Default to writing **no comment**. Only add one when removing it would confuse a future reader.
+
+## Boy Scout Rule
+
+Leave the file cleaner than you found it. Fix one small inconsistency on the way through, do not embark on a separate refactor.

package/runtime/skills/okstra-coding-preflight/languages/java.md

@@ -0,0 +1,64 @@
+# Java Conventions
+
+## Style guide
+
+Google Java Style Guide is the default. If the project ships its own (`CONTRIBUTING.md`, `.editorconfig`, `checkstyle.xml`, `google-java-format` config), follow that instead.
+
+## Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Class / interface / enum | UpperCamelCase | `ImmutableList`, `HashIntegrationTest` |
+| Method / variable / parameter | lowerCamelCase | `sendMessage`, `computedValues` |
+| Constant (`static final` + immutable value) | UPPER_SNAKE_CASE | `MAX_COUNT`, `DEFAULT_TIMEOUT` |
+| Package | lowercase, no underscores | `com.example.deepspace` |
+| Type variable | single letter or short PascalCase | `T`, `E`, `Result` |
+| Test class | `<ClassUnderTest>Test` / `<ClassUnderTest>IT` | `UserServiceTest`, `OrderRepositoryIT` |
+
+## Formatting
+
+- Indent: **2 spaces**, never tabs.
+- Column limit: **100** characters.
+- Brace style: K&R — opening brace on the same line.
+- One statement per line.
+- Always brace `if`, `else`, `for`, `while`, `do`, even for single-statement bodies.
+- `switch` statements must be exhaustive — supply a `default` case, or rely on enum/sealed-type coverage.
+
+## Required practices
+
+- `@Override` on every override (including interface methods).
+- Never silently swallow exceptions. If you intentionally ignore one, leave a one-line comment stating why.
+- Access static members via the class name (`Foo.bar()`, not `instance.bar()`).
+- Do not use finalizers. Use `try-with-resources` for `AutoCloseable` and `java.lang.ref.Cleaner` for native handles.
+- Declare local variables near first use, with the narrowest possible scope.
+- Prefer `List.of(...)` / `Map.of(...)` / `Set.of(...)` for small immutable collections.
+- Prefer `Optional<T>` as a return type for "might be missing"; never use `Optional` for fields, parameters, or collection elements.
+- Use `record` for plain data carriers (Java 16+).
+- Use `var` only when the right-hand side makes the type obvious to a reader.
+
+## Tests
+
+- Framework: **JUnit 5** unless the project uses TestNG or JUnit 4.
+- File suffix: `*Test.java` for unit, `*IT.java` for integration.
+- Method naming: `methodUnderTest_condition_expectedResult` (e.g. `parse_emptyInput_throws`).
+- Use **AssertJ** or JUnit's `assertThat` for fluent assertions; avoid bare `assertTrue(a == b)`.
+- One logical assertion per test. Multiple `assertThat` lines on the *same state* are fine.
+- No `Thread.sleep` in tests — use **Awaitility** for async.
+- Mock at process boundaries only (HTTP, DB, time, randomness). Do not mock value objects or DTOs.
+- Use `@Nested` to group related test cases.
+- Use parameterized tests (`@ParameterizedTest` + `@CsvSource` / `@MethodSource`) for table-driven coverage.
+
+### Self-mock signals to refuse (rule from `clean-code.md` → Testing discipline)
+
+- A field annotated with **both** `@InjectMocks` *and* `@Spy` — the SUT is being wrapped as a spy so its own methods can be stubbed. Drop `@Spy`; stub only the `@Mock` collaborators on the same class.
+- `Mockito.spy(realSut)` followed by `doReturn(...).when(spy).someMethod(...)` — same anti-pattern, manually constructed.
+- `MockedStatic<SomeUtil>` when `SomeUtil` is the unit under test rather than a dependency.
+- `ReflectionTestUtils.setField(sut, "privateState", ...)` to drive a branch, or `ReflectionTestUtils.invokeMethod(sut, "privateHelper")` to assert on a private helper — that's reaching into privates and breaks behavioral-testing discipline.
+
+What's fine: `@Mock` on collaborators injected into `@InjectMocks`, `verify(collaborator).methodCall(...)` on outcome boundaries (repository save, mailer send, gateway charge).
+
+## Formatter / linter to run
+
+- `google-java-format` (preferred) or the `spotless` Gradle/Maven plugin.
+- `checkstyle`, `spotbugs`, `error-prone` if configured by the project.
+- Run before commit: `./gradlew spotlessApply check` (or the project's equivalent).

package/runtime/skills/okstra-coding-preflight/languages/javascript-typescript.md

@@ -0,0 +1,87 @@
+# JavaScript / TypeScript Conventions
+
+## Style guide
+
+Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.json|.cjs|.mjs)`, `.prettierrc`, `tsconfig.json`, and `package.json` `engines` override these defaults — read them **first**.
+
+## Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Variable / function | camelCase | `userCount`, `fetchProfile` |
+| Class / type / interface / enum | PascalCase | `UserProfile`, `HttpClient`, `Status` |
+| Constant (true immutable, module-level) | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Boolean variable | `is` / `has` / `should` / `can` prefix | `isLoading`, `hasPermission`, `shouldRetry` |
+| React component | PascalCase | `UserCard` |
+| Hook | `use` prefix | `useAuth` |
+| File: React component | matches component name | `UserCard.tsx` |
+| File: everything else | kebab-case | `format-date.ts` |
+
+## Formatting
+
+- Indent: **2 spaces**.
+- Semicolons: pick one project-wide and never mix.
+- Single quotes for strings, backticks for templates and any string needing interpolation.
+- Trailing commas in multi-line literals / params.
+- Prefer arrow functions for callbacks and small utilities; reserve `function` for top-level named declarations and class methods.
+- Destructure when accessing 2 or more properties: `const { id, name } = user`.
+
+## TypeScript-specific (mandatory)
+
+- `tsconfig.json`: `"strict": true`. No exceptions. `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are recommended.
+- **Never** use `any`. If a type is truly unknown, use `unknown` and narrow.
+- Let inference do its job for locals. Declare explicit types at:
+  - Exported function signatures (parameters **and** return type).
+  - Public class members.
+  - Empty literals where inference would default to `never` or `{}` — `const items: User[] = []`.
+- Use `readonly` for arrays, properties, and parameters that must not mutate.
+- Discriminated unions over loose objects with optional flags. Use a literal `kind` / `type` field.
+- Type guards (`function isX(v): v is X`) over casts (`as X`). Casts are a last resort.
+- `interface` for object shapes that may be extended; `type` for unions / mapped / conditional types.
+- Generics: meaningful names when single letters are unclear (`TUser`, `TResult`).
+- Never disable rules inline (`// eslint-disable`, `// @ts-ignore`, `// @ts-expect-error`) without a one-line comment explaining why.
+
+## Required practices
+
+- `const` by default, `let` only when reassigned. `var` is **forbidden**.
+- Use `===` / `!==`, never `==` / `!=`.
+- Use optional chaining `?.` and nullish coalescing `??` instead of long `&&` / `||` ladders.
+- `for...of` over indexed `for` loops on iterables. `map` / `filter` / `reduce` over manual loops when transforming.
+- `async` / `await` over raw `.then` chains. Mixing is forbidden in one function.
+- Throw `Error` instances, never strings. Subclass `Error` for typed domain errors.
+- Avoid `export default` unless the file has exactly one obvious export — named exports are easier to refactor and rename.
+- Do not mutate function parameters or imported modules.
+
+## Tests
+
+- Framework: **Vitest**, **Jest**, or Node's built-in `node:test`. Match what the project uses.
+- File suffix: `*.test.ts` or `*.spec.ts`, colocated with source (`src/foo/bar.ts` → `src/foo/bar.test.ts`).
+- Structure: `describe(unit, () => { it('does X when Y', () => { ... }) })`.
+- **One behaviour per `it` block.**
+- Async tests: `await` every promise. Returning a promise without `await` hides assertion failures.
+- Mocking: prefer dependency injection over module mocks. When you must mock, use `vi.mock` / `jest.mock` and reset between tests (`beforeEach(() => vi.clearAllMocks())`).
+- React: **React Testing Library**, not Enzyme. Query by role / label / text, not by class or test-id, unless nothing else works.
+- Snapshot tests only for stable, intentional output. Snapshots that "just changed" are noise.
+
+### Self-mock signals to refuse (rule from `clean-code.md` → Testing discipline)
+
+- `jest.spyOn(sut, 'someMethod').mockReturnValue(...)` / `.mockResolvedValue(...)` / `.mockImplementation(...)` where `sut` is the subject under test.
+- `jest.spyOn(FooService.prototype, 'someMethod').mockReturnValue(...)` in `foo.service.spec.ts`.
+- `sut.calculateTotal = jest.fn(...)` — manually overwriting a method on the SUT instance.
+- `vi.mocked(sut)` followed by stubbing the SUT's own methods.
+- Reaching into privates via `(sut as any).privateMethod()` or `sut['privateMethod']()` — the issue is the *private access*, not the cast itself.
+
+`any` / `as any` in `*.spec.ts` / `*.test.ts` is otherwise fine — test setup justifies looser typing. Only flag it when it's the vehicle for one of the violations above.
+
+What's fine: `jest.fn()` for collaborator stubs passed via constructor DI, `vi.mock('../mailer')` to fake a side-effecting module at the boundary, `expect(mailer.send).toHaveBeenCalledWith(...)` on an outcome boundary.
+
+## Formatter / linter to run
+
+- `prettier --write .` (formatting).
+- `eslint --fix .` (style + correctness).
+- `tsc --noEmit` (type check).
+- All three should pass before commit. CI should fail on warnings, not just errors.
+
+## Forbidden and Prohibited
+
+- never use any type assertions (`as` or ``)

package/runtime/skills/okstra-coding-preflight/languages/kotlin.md

@@ -0,0 +1,69 @@
+# Kotlin Conventions
+
+## Style guide
+
+Kotlin official coding conventions (kotlinlang.org/docs/coding-conventions.html). In IntelliJ / Android Studio enable via *Settings → Editor → Code Style → Kotlin → Set from… → Kotlin style guide*.
+
+## Naming
+
+| Element | Convention | Example |
+|---|---|---|
+| Class / object / interface | UpperCamelCase | `DeclarationProcessor` |
+| Function / property / parameter | lowerCamelCase | `processDeclarations`, `isReady` |
+| Constant (`const val` or top-level immutable) | SCREAMING_SNAKE_CASE | `MAX_COUNT`, `USER_NAME_FIELD` |
+| Backing property | leading underscore | `_elementList` (private), `elementList` (public) |
+| Package | lowercase, no underscores | `com.example.feature` |
+| Test function | backticked sentence | `` `parses empty input` `` |
+
+## Formatting
+
+- Indent: **4 spaces**.
+- Opening brace at end of line, closing brace on its own line.
+- Lambdas: spaces around braces and arrow — `list.filter { it > 10 }`, `map.forEach { (k, v) -> println("$k=$v") }`.
+- Trailing comma in multi-line lists / parameters / `when` arms (since Kotlin 1.4).
+- Function expression body when the body is a single expression: `fun double(x: Int) = x * 2`.
+
+## Required practices
+
+- Prefer `val` over `var`. Mutability is opt-in.
+- Default and named arguments replace constructor / function overloads.
+- Prefer the standard library: `filter`, `map`, `groupBy`, `associateBy`, `chunked`, `windowed` over manual loops.
+- String templates: `"Hello, $name"`, never `"Hello, " + name`.
+- Extension functions are encouraged. Keep them `internal` or file-private unless they belong to a public API.
+- `data class` for value-holders. Do not attach behaviour to them.
+- Sealed classes / sealed interfaces for closed hierarchies — exhaustive `when` catches new cases at compile time.
+- Null safety: never chain `!!`. Use `?.`, `?:`, `let`, `requireNotNull(x) { "why" }`, `checkNotNull(x)`.
+- Use `inline` for higher-order functions that are called frequently and pass lambdas, **not** as a default optimization.
+- Use `object` for true singletons and `companion object` only when JVM-visible static members are needed.
+
+## Coroutines
+
+- Pick **one** coroutine framework per module. Do not mix coroutines with `CompletableFuture` chains in the same flow.
+- Never `runBlocking { ... }` inside another coroutine.
+- Pass `CoroutineScope` explicitly; do not use `GlobalScope`.
+- Cancel scopes deterministically on lifecycle teardown.
+- Use `withContext(Dispatchers.IO)` only for blocking I/O — most application code stays on the default dispatcher.
+
+## Tests
+
+- Framework: **JUnit 5 + kotlin.test**, or **Kotest**. Match the project.
+- Backticked function names are idiomatic for tests: `` fun \`returns empty list when input is empty\`() `` .
+- Use `kotlinx-coroutines-test`'s `runTest` for suspend tests.
+- Use **MockK** over Mockito for Kotlin (handles `final` classes, coroutines, and extension functions correctly).
+- Prefer property-based tests (Kotest's `forAll`) for pure transformations.
+- Assertion libraries: `kotest-assertions` (`shouldBe`, `shouldThrow`) or AssertJ.
+
+### Self-mock signals to refuse (rule from `clean-code.md` → Testing discipline)
+
+- `spyk(sut)` followed by `every { sut.someMethod() } returns ...` — the SUT's own method is replaced; the test verifies wiring, not behavior.
+- `coEvery { sut.suspendMethod() } returns ...` for the suspend equivalent.
+- `mockkObject(SomeSingleton)` / `mockkStatic(...)` when `SomeSingleton` *is* the unit under test.
+- Reflection or `internal` visibility hacks (`@VisibleForTesting`, `callPrivateFunc` extensions) used to assert on private helpers — that's the implementation-coupling smell, not just a self-mock.
+
+What's fine: `mockk<Collaborator>()` for injected dependencies, `coEvery {}` on those collaborators, and `verify {}` on outcome boundaries (mailer, gateway, repository write).
+
+## Formatter / linter to run
+
+- **ktlint** and / or **detekt**.
+- `./gradlew ktlintFormat detekt` if the plugins are configured.
+- Run before commit.

package/runtime/skills/okstra-coding-preflight/languages/nodejs.md

@@ -0,0 +1,66 @@
+# Node.js Conventions (server-side)
+
+Load this **in addition to** [javascript-typescript.md](javascript-typescript.md). JS / TS rules still apply; this file adds the server-specific layer.
+
+## Architecture
+
+- Separate layers: **HTTP / transport** → **business / domain** → **data access**. No layer skips downward; no layer reaches upward.
+- Request handlers are thin: parse input → call a service → format response.
+- Business logic is framework-agnostic. Do **not** import Express / Fastify / Nest types in service or domain modules.
+- One file, one concern. A 1000-line `index.ts` is a structural bug.
+- Dependency injection (constructor or factory) over module-level singletons. Singletons are not testable.
+
+## Error handling
+
+- Distinguish **operational errors** (network, validation, expected business state) from **programmer errors** (bugs, broken invariants). Recover from operational, crash on programmer.
+- Use `async` / `await` with `try` / `catch` at the layer that knows what to do. Catching just to rethrow with no extra value is a smell.
+- Centralise error handling in middleware. Every route returns through it.
+- Always handle event-emitter `'error'` events — an unhandled emitter error crashes the process.
+- Throw subclasses of `Error` (`class ValidationError extends Error {}`) so handlers can `instanceof` them.
+- Process-level: `process.on('unhandledRejection', ...)` and `process.on('uncaughtException', ...)` should log and exit gracefully. Do not swallow.
+
+## Async discipline
+
+- Never mix callbacks with promises in the same flow. Use `util.promisify` at the boundary, once.
+- Prefer `for await...of` over manual cursor / stream loops.
+- `Promise.all` for independent parallel work, `Promise.allSettled` when one failure must not cancel the rest.
+- Set explicit timeouts on **every** outgoing HTTP / DB call (no infinite waits, no defaults).
+- Use `AbortController` to cancel in-flight work when the upstream caller goes away.
+
+## Security baseline
+
+- All configuration in environment variables (loaded via `dotenv` in dev only). Validate them at startup with `zod`, `envalid`, or similar — fail fast on missing / invalid values.
+- Never log secrets, auth-endpoint request bodies, full JWTs, or PII.
+- HTTPS only at the edge. Behind a TLS-terminating proxy is fine; never speak plain HTTP across the public internet.
+- Use `helmet` for security headers, `cors` with an explicit allowlist (no `*` in production).
+- Validate every untrusted input (`zod`, `joi`, `valibot`). Validation belongs at the boundary, not inside services.
+- Rate-limit public endpoints (`express-rate-limit` or upstream proxy).
+- Run `npm audit` / `pnpm audit` regularly. Patch promptly.
+
+## Performance
+
+- **Streams** (`fs.createReadStream`, `pipeline`) for large payloads — never load multi-MB files fully into memory.
+- Multi-core: `cluster`, PM2, or a process manager. Pure async will not save you from a single-thread CPU bottleneck.
+- Keep request handlers off the event loop. Offload heavy CPU work to a `worker_thread` or a queue.
+- Connection pool for every DB client. `pg`, `mysql2`, and `mongoose` default to a pool — do **not** create a client per request.
+- Cache idempotent reads at an explicit layer (Redis, in-memory LRU). Do not bolt caching into a service method.
+- Use `Buffer`/typed arrays for binary data, not strings.
+
+## Logging
+
+- Structured logger (`pino`, `winston`). Emit **JSON**, not human strings.
+- Every request: request id, method, path, status, latency. Propagate the request id through downstream calls via `AsyncLocalStorage`.
+- Levels: `error` (pageable), `warn` (suspicious), `info` (business event), `debug` (off in production).
+- Never `console.log` in production code. `console.log` exists for ad-hoc REPL only.
+
+## Tests
+
+- Unit-test services and domain functions with zero Node-runtime dependencies — no `fs`, no `net`, no real DB.
+- Integration-test the HTTP layer with `supertest` against the real Express / Fastify app instance.
+- `testcontainers` for DBs when the production DB has features (locks, full-text, JSONB, partitioning) you depend on. In-memory fakes lie about behaviour.
+- Test the error paths. Coverage of the happy path only is not coverage.
+
+## Formatter / linter / tools
+
+- Same as JS / TS: `prettier`, `eslint`, `tsc`.
+- `npm run lint && npm test` (or the project's equivalent) must pass before any commit.