okstra 0.49.0 → 0.51.0

package/runtime/python/okstra_ctl/worktree.py

@@ -172,7 +172,7 @@ def preview_worktree_decision(
     helpers so preview never diverges from the actual provisioning result.
     """
     project_root = Path(project_root)
-    if not _is_git_repo(project_root):
+    if not is_git_work_tree(project_root):
         return WorktreeDecision(status="skipped-not-git", path=str(project_root))
     if _is_inside_non_main_worktree(project_root):
         return WorktreeDecision(status="skipped-in-worktree", path=str(project_root))
@@ -232,8 +232,16 @@ def _is_inside_non_main_worktree(project_root: Path) -> bool:
     return common_abs != per_tree_abs
 
 
-def _is_git_repo(project_root: Path) -> bool:
-    res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+def is_git_work_tree(project_root: Path) -> bool:
+    """project_root 가 git work tree 내부인지 판정하는 public git-introspection seam.
+
+    git 미설치(FileNotFoundError) 를 포함한 모든 실패는 False — 호출자(migrate
+    등)가 non-git 레이아웃으로 안전하게 폴백할 수 있도록 한다. 과거 migrate.py
+    가 같은 판정을 자체 구현(`--show-toplevel`)했는데 이 seam 으로 통합한다."""
+    try:
+        res = _git(project_root, "rev-parse", "--is-inside-work-tree")
+    except (OSError, FileNotFoundError):
+        return False
     return res.returncode == 0 and res.stdout.strip() == "true"
 
 
@@ -260,7 +268,7 @@ def _resolve_commit_sha(cwd: Path, ref: str) -> str:
     return res.stdout.strip()
 
 
-def _main_worktree_path(project_root: Path) -> Path:
+def main_worktree_path(project_root: Path) -> Path:
     """Locate the repository's MAIN worktree (the original checkout).
 
     `git worktree list --porcelain` lists worktrees in a stable order
@@ -601,7 +609,7 @@ def provision_task_worktree(
             "work-category before retrying."
         )
 
-    main_root = _main_worktree_path(project_root)
+    main_root = main_worktree_path(project_root)
     requested_base = (base_ref or "").strip()
     if not requested_base and require_base_ref:
         raise RuntimeError(

package/runtime/schemas/final-report-v1.0.schema.json

@@ -83,6 +83,10 @@
         "approved": {
           "type": "boolean",
           "description": "사용자 승인 플래그. report-writer 는 항상 false 로 발행하고, 사용자가 `--approve` 또는 직접 편집으로 true 로 토글합니다. `implementation` task-type 의 prepare 단계가 `--approved-plan` 으로 지정된 보고서의 이 필드를 읽어 진입 여부를 결정합니다. 다른 task-type 에서는 의미 없이 false 로 유지됩니다."
+        },
+        "implementationOption": {
+          "type": "string",
+          "description": "유저가 implementation-planning final-report 에서 고른 Option Candidate 이름. report-writer 는 항상 빈 문자열로 발행하고, 사용자가 `--implementation-option <name>` 또는 직접 편집으로 채웁니다. `implementation` task-type 이 이 값으로 진행하며, 비어 있으면 plan 의 `Recommended Option` 으로 폴백합니다. 다른 task-type 에서는 의미 없이 빈 값으로 유지됩니다."
         }
       }
     },

package/runtime/skills/okstra-brief/SKILL.md

@@ -760,7 +760,7 @@ If the list is non-empty, run **one** `AskUserQuestion`:
   1. `Yes — collect now (Recommended)` — proceed to 6.5c.
   2. `No — leave for the downstream phase` — set
      `reporter-confirmations: skipped`. The phase will promote each
-     pending row into its own `## 5. Clarification Items` as
+     pending row into its own `## 1. Clarification Items` as
      `Blocks=next-phase` (`Blocks=approval` only in
      `implementation-planning`); see each phase profile's "Brief
      consumption" addendum.

package/runtime/skills/okstra-coding-preflight/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: okstra-coding-preflight
+description: Provides language-specific coding conventions, idioms, and test-writing guidance for Java, Kotlin, JavaScript, TypeScript, Node.js, Python, SQL, and Rust. okstra lead/workers MUST consult this skill before writing, editing, refactoring, or testing code in any of these languages — including any new file, function, or test — even when the task seems simple enough to handle directly. Detect the target language from the file extension, project config (package.json/Cargo.toml/pyproject.toml/pom.xml/build.gradle), or task brief, and apply the matching conventions.
+user-invocable: false
+---
+
+# okstra Code Preflight
+
+## These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
+
+1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
+2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
+3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
+4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
+5. **Function length cap — 50 lines** — 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. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
+
+
+## Quick start
+
+Before writing or editing **any** code:
+
+1. Identify the target language (file extension, project config, or explicit user request).
+2. Read the matching language reference from `languages/`.
+3. Read [clean-code.md](clean-code.md) for the language-agnostic principles.
+4. **Check for architecture overlays.** If the project uses ports-and-adapters (signals: `domain/` + `ports/` + `adapters/` folders, `*.port.*` files, NestJS hex split), also read [architecture/hexagonal.md](architecture/hexagonal.md). Record the detected layout in one line so later edits don't re-discover it.
+5. In **one short sentence** to the user, state which conventions you will apply (e.g., *"Applying Kotlin conventions + hexagonal overlay; domain at `src/domain/`."*).
+6. Then write code.
+
+If the language is not listed below, stop and ask the user for the canonical style guide they want to follow before writing code.
+
+## Language router
+
+| Language | Reference | Triggers |
+|---|---|---|
+| Java | [languages/java.md](languages/java.md) | `.java`, `pom.xml`, `build.gradle` |
+| Kotlin | [languages/kotlin.md](languages/kotlin.md) | `.kt`, `.kts`, `build.gradle.kts` |
+| JavaScript / TypeScript | [languages/javascript-typescript.md](languages/javascript-typescript.md) | `.js`, `.ts`, `.tsx`, `.jsx` |
+| Node.js (server) | [languages/nodejs.md](languages/nodejs.md) | `package.json` with server entry, `express`, `fastify`, `nestjs` |
+| Python | [languages/python.md](languages/python.md) | `.py`, `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg` |
+| SQL | [languages/sql.md](languages/sql.md) | `.sql`, migration directories, `prisma/schema.prisma`, raw queries embedded in code |
+| Rust | [languages/rust.md](languages/rust.md) | `.rs`, `Cargo.toml` |
+
+For Node.js work, load **both** `javascript-typescript.md` and `nodejs.md`.
+
+## Architecture overlays
+
+Loaded **in addition to** the language reference when the project matches. Overlays add architectural rules that cut across languages.
+
+| Overlay | Reference | When to load |
+|---|---|---|
+| Hexagonal (ports & adapters) | [architecture/hexagonal.md](architecture/hexagonal.md) | Project has `domain/` + `ports/` + `adapters/` (or equivalent: `core/`, `infrastructure/`, `application/`), `*.port.*` files, or `abstract class` files at a domain boundary. Confirm once with the user if ambiguous. |
+
+If you suspect an overlay applies but the layout is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer.
+
+## Mandatory pre-write checks (every language)
+
+- [ ] Language reference read for this turn.
+- [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
+- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change.
+- [ ] **Testing discipline:** the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called.
+- [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`.
+- [ ] Existing code searched: `grep` for the symbol / file / identifier you are about to add. Do not duplicate.
+- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this skill on conflict.**
+
+## Boundaries
+
+- This skill does **not** auto-format. Run the project's formatter yourself.
+- This skill does **not** replace repo-local rules. Repo rules win on conflict.
+- This skill does **not** cover every language. If the target language is missing, stop and ask.

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 ``)