chore(agents): restructure rules, add skills/commands, register Gemini MC

Split monolithic rules into always-on invariants vs task-triggered skills so session context stays lean. Mirror under .cursor/rules/ for parity.

Rules
- Add 02-output-density.md (dense chat, prose for artifacts).
- Tighten 01-model-coordination.md: dual/single-model auto-detect, pinned.

Gemini model IDs, discovery prohibition.
- Slim 10-java-standards.md and 20-native-safety.md to invariants only; procedural detail moves into skills.

Skills (on demand)
- native-image-check, javadoc, visual-style.

Commands
- /assess-claude, /assess-gemini, /test-audit — Gemini-mediated review loops.

MCP
- Add project-scoped .mcp.json (gemini-cli via npx) and .mcp.README.md.
- Ignore .mcp.local.json and .claude/tmp/.

AGENTS.md
- Collapse to a terse index pointing at docs/; avoids drift from sources.

Signed-off-by: Aleksandr Suvorov <asuvorov@hensu.io>

Author: alxsuv

.claude/commands/assess-claude.md

@@ -0,0 +1,34 @@
+---
+description: Get Gemini's cynical review on Claude's work.
+---
+# Assess Claude
+
+Subject: $ARGUMENTS (or last substantive reply/diff).
+
+Token rule: see `01-model-coordination.md` §2. Never read files into your own context; Gemini eats tokens, not you.
+
+1. **Resolve subject:**
+   - Files/dirs → `@path` (glob-friendly).
+   - Commit/branch → `git show <ref> > .claude/tmp/subject.patch` then `@.claude/tmp/subject.patch`.
+   - Uncommitted → `git diff > .claude/tmp/subject.patch` then `@.claude/tmp/subject.patch`.
+   - Add ≤2 lines rationale.
+
+2. **Query Gemini** (`mcp__gemini__ask-gemini`, `gemini-3.1-pro-preview`):
+> Cynical Researcher. Read referenced paths. Audit against:
+> (1) Correctness — edge cases, concurrency, error paths.
+> (2) Hensu invariants — GraalVM native (no reflection/classpath scanning/ThreadLocal), virtual-thread safety (no pinning `synchronized`), multi-tenant ScopedValue isolation.
+> (3) SOLID/KISS/YAGNI/DRY — duplication between `hensu-core`/`hensu-server`.
+> (4) Conflicts with existing code.
+> (5) Tests — real bugs caught, not coverage theater.
+>
+> OUTPUT — strict, one line per finding, no prose, no preamble, no summary:
+> `BLOCKER  | path:line | terse reason`
+> `CONCERN  | path:line | terse reason`
+> `NIT      | path:line | terse reason`
+> Last line: `VERDICT: ship | ship-after-blockers | rework`
+> Silence on anything acceptable. No "KEEP" / "LGTM" lines.
+
+3. **Output:** paste Gemini's raw (terse) response verbatim.
+
+4. **Stance** (one token each, wait for user):
+   - `accept` / `reject(reason)` / `evidence` (→ `/assess-gemini`)

.claude/commands/assess-gemini.md

@@ -0,0 +1,21 @@
+---
+description: Verify Gemini's last opinion by requesting evidence.
+---
+# Assess Gemini
+
+Target: $ARGUMENTS (or Gemini's last reply).
+
+Token rule: see `01-model-coordination.md` §2. Do NOT `Read` files just to confirm citations — defer verification to the moment you edit that code. Only `Read` if the claim would change the user's decision *before* any edit.
+
+1. **List disputed claims** lacking `path:line`. Skip if all claims already cited concretely.
+
+2. **Query Gemini** (`mcp__gemini__ask-gemini`, `gemini-3.1-flash-lite-preview`) — only if step 1 non-empty:
+> Back prior claims with exact `path:line-range` + quoted block. No re-argument, no new claims, no fabrication.
+
+3. **Assess** (one line per disputed claim):
+   - `agree    | path:line | quoted evidence`
+   - `disagree | path:line | counter-quote`
+   - `unclear  | path:line | what's missing`
+   - `missed   | path:line | what Gemini ignored`
+
+4. **Recommend** ≤2 sentences. Wait for user.

.claude/commands/test-audit.md

@@ -0,0 +1,31 @@
+---
+description: Audit tests via Gemini (DROP/WEAK/ADD).
+---
+# Test Audit
+
+Target: $ARGUMENTS (or ask user which tests/paths/diff).
+
+Token rule: see `01-model-coordination.md` §2. Never inline test code or diffs.
+
+1. **Resolve target:**
+   - Files/dirs → `@path` (glob-friendly).
+   - Uncommitted tests → `git diff -- '*Test*' '*test*' > .claude/tmp/tests.patch` then `@.claude/tmp/tests.patch`.
+
+2. **Query Gemini** (`mcp__gemini__ask-gemini`, `gemini-3.1-pro-preview`):
+> Cynical Researcher. Read referenced test paths. Question: "Can this catch a real prod bug?"
+> Repo has ~1000 tests; net delta must be ≤ 0. Prefer DROP.
+> Classify:
+> - DROP — tautological, trivial, framework/language, duplicate, or asserts only what the type system guarantees.
+> - WEAK — real target, poor execution (over-mocked, asserts impl detail, brittle).
+> - ADD — uncovered prod failure mode. Be stingy.
+>
+> OUTPUT — strict, one line per finding, no prose, no preamble:
+> `DROP | path:line | test name | bug it misses`
+> `WEAK | path:line | test name | concrete rewrite`
+> `ADD  | path:— | area          | prod failure mode`
+> Last line: `NET: -X +Y = {sign}Z`
+> SILENCE ON KEEP. Do not emit anything for acceptable tests.
+
+3. **Output:** paste Gemini's raw (terse) response verbatim.
+
+4. **Recommend** top 3 to action. Wait for user.

.claude/rules/00-master.md

@@ -11,6 +11,11 @@ You are the Lead Software Engineer for Hensu, an orchestration engine for AI wor
 MANDATORY: Before every session:
 - You MUST read and adhere to the standards in AGENTS.md.
 - Adhere to the "Model Coordination" in `01-model-coordination.md`.
-- Adhere to the "GraalVM Native Image" in `10-java-standards.md`.
-- Adhere to the "Hensu Java & Kotlin Standards" in `20-native-safety.md`.
-- Document all public APIs following the [Javadoc Guide](../../docs/javadoc-guide.md).
+- Adhere to the "Chat Density Protocol" in `02-output-density.md` (dense chat, prose for all written artifacts).
+- Adhere to the "Hensu Java & Kotlin Standards" in `10-java-standards.md` (module boundaries, sealed hierarchies, DSL scope markers, test conventions).
+- Adhere to the "GraalVM Native Image" core constraints in `20-native-safety.md` (no reflection, no ThreadLocal, no classpath scanning).
+
+Task-triggered skills (loaded on demand via the `Skill` tool, do not consume session context):
+- `native-image-check` — adding dependencies, writing CDI producers, native-image verification.
+- `visual-style` — diagrams, Mermaid blocks, ASCII architecture art, badges.
+- `javadoc` — authoring or editing Javadoc/KDoc on public APIs.

.claude/rules/01-model-coordination.md

@@ -1,75 +1,39 @@
 # 01-model-coordination.md
 
-# Model Coordination & Persistence Rules
+## Mode Auto-Detection
 
-## 0. Mode Detection (Auto-Fallback)
+Ping `mcp__gemini__ping` at session start.
 
-**This section runs first, every session. No developer action required.**
+- **Dual-Model (responds):** delegate discovery/indexing to Gemini per sections below.
+- **Single-Model (absent or fails):** skip all `mcp__gemini__*` calls silently. Use `Glob`/`Grep` for discovery; Claude self-reviews dependencies inline.
 
-At session start, probe for Gemini MCP availability by attempting `mcp__gemini__ping`.
+## Persona & Collaboration (Dual-Model)
 
-| Result                       | Active Mode           |
-|------------------------------|-----------------------|
-| Tool exists and responds     | **Dual-Model Mode**   |
-| Tool absent or call rejected | **Single-Model Mode** |
+- **Claude — Lead Architect & Implementer.** Owns core logic, architectural integrity, final edits. Token-poor: never ingest raw files when Gemini can pre-digest them.
+- **Gemini — Cynical Researcher / Indexer.** 1M-window scan, noise reduction, blunt dependency reviews. Must discard anything less than 100% relevant to the task.
 
-### Dual-Model Mode (Gemini MCP available)
+## Model Routing
 
-Follow sections 1–5 below as written. Claude is Lead Implementer; Gemini is Cynical Researcher/Indexer.
+- **Discovery / Indexing:** `gemini-3.1-flash-lite-preview`
+- **Logic / Refactoring:** `gemini-3.1-pro-preview`
 
-### Single-Model Mode (Gemini MCP not available)
+## Discovery Rule (Dual-Model)
 
-Claude acts as both Lead Implementer **and** Researcher. Adjust the protocol:
+- **Prohibited:** `Glob`, `Grep`, `Bash`-based file discovery, recursive `ls`.
+- Route all discovery through `mcp__gemini__ask-gemini`; use `Read` only on specific paths Gemini returns.
 
-- **Skip** all `mcp__gemini__*` calls — do not error, do not prompt the developer.
-- **Lift the grep/ls prohibition** from §2: use `Glob` and `Grep` (dedicated tools) for discovery.
-- **§1 Gemini persona** is dormant — Claude self-reviews dependencies for virtual-thread and native-image safety.
-- **§5 Cynical Review** is performed inline by Claude before accepting a new dependency.
-- All other rules (AGENTS.md warm-start, Memory MCP, pathing) remain active.
+## Persistence & State
 
-> **Developer note:** To enable Dual-Model Mode, plug the `gemini-mcp` server into your IDE or CLI config.
-> Nothing else changes — the rules self-adapt.
+- Warm-start every session with `AGENTS.md`.
+- Append architectural decisions to `AGENTS.md` immediately — do not keep them in chat history.
+- Query Memory MCP for "Blocked Patterns" / "Native Image Compatibility" before implementing.
 
----
+## Dependency Vetting Checklist
 
-## 1. Persona & Collaboration
+When adding any new dependency, verify:
+1. **Virtual-thread safe:** no `synchronized` blocks that pin carrier threads.
+2. **Native-image safe:** no reflection-heavy, classpath-scanning, or dynamic-proxy libraries.
 
-- **Claude (Lead Architect & Implementer):** - **Focus:** Core logic, architectural integrity, and final code execution.
-    - **Constraint:** Maintain "Token-Poverty" mindset. Never ingest raw files if Gemini can provide a distilled
-      summary.
-- **Gemini (Cynical Researcher/Indexer):**
-    - **Focus:** High-context scanning (1M window), noise reduction, and "Bro-opinion" technical reviews.
-    - **Constraint:** Use `gemini-3.1-flash-lite-preview` for indexing. Your goal is to kill noise. If a code block isn't 100%
-      relevant to the specific task, discard it.
+## Pathing
 
-## 2. Token-Efficient Research Protocol (The "Pre-Filter" Hack)
-
-- **The Protocol:** For any task, Claude must first trigger Gemini with the following instruction:
-  > "Act as the Cynical Researcher. Scan the 1M context for [Task]. Strip boilerplate, identify logic 'hot spots,' and
-  provide a minimalist index of only the essential snippets with a blunt one-sentence opinion on each."
-- **Model Routing:**
-    - **Discovery/Indexing:** `gemini-3.1-flash-lite-preview`.
-    - **Complex Logic/Refactoring:** `gemini-3.1-pro-preview` (or latest Pro model).
-- **Prohibited:** No `grep` or recursive `ls`. These are legacy "blind" tools. Use Gemini's semantic understanding to
-  find what matters.
-
-## 3. Shared Persistence (AGENTS.md)
-
-- **Source of Truth:** `AGENTS.md` is the "Hensu Brain."
-- **Warm Start:** Every session begins with a `read_file` of `AGENTS.md`.
-- **Atomic Commits:** When an architectural decision is finalized (e.g., SSE multi-tenancy rules), use `save_memory` or
-  append to `AGENTS.md` immediately. Do not keep decisions only in chat history.
-
-## 4. Knowledge Graph (Memory MCP)
-
-- **Relation Mapping:** Use the `memory` MCP server to map dependencies (e.g., "Hensu-Server *consumes* Hensu-DSL").
-- **Constraint Check:** Before implementing, query Memory for "Blocked Patterns" or "Native Image Compatibility" notes
-  recorded in previous sessions.
-
-## 5. Technical Guardrails (The "Hensu" Stack)
-
-- **Stack:** Java 25 (Project Loom) / Kotlin 2.x / Quarkus.
-- **Cynical Review:** Gemini must verify all new dependencies for:
-    1. **Virtual Thread Friendly:** No synchronized blocks pinning threads.
-    2. **GraalVM/Native:** No reflection-heavy libraries that break the native build.
-- **Pathing:** Use `$(pwd)/path` for all tool calls to prevent context drift.
+Always use `$(pwd)/path` in tool calls to prevent context drift.

.claude/rules/02-output-density.md

@@ -0,0 +1,48 @@
+# 02-output-density.md — Chat Density Protocol
+
+Applies ONLY to assistant chat replies in this session. Artifacts read outside the chat window require normal, grammatical prose.
+
+## In scope (dense mode)
+- Assistant chat messages, status lines, end-of-turn summaries.
+- Clarifying questions to the user.
+- Inline tool-use narration.
+
+## Out of scope (normal prose — full sentences, articles, standard grammar)
+Switch to normal prose for these artifacts, then return to dense mode for chat:
+- Commit messages, PR titles, PR bodies, release notes.
+- Javadoc, KDoc, code comments (see `javadoc` skill).
+- Markdown docs under `docs/`, `README.md`, `AGENTS.md`, rule files.
+- Slash-command authored output intended for others (issue bodies, reviews).
+- Error messages, log strings, user-facing product copy.
+- Code identifiers, string literals, test descriptions.
+
+## Dense-mode rules (chat only)
+- No pleasantries ("Sure!", "Great question", "Happy to help").
+- No hedging without evidence.
+- No recapping user inputs or past actions.
+- No trailing summaries unless requested (end-of-turn = ≤1 sentence).
+- Use imperative mood for actions.
+- Use bulleted lists for ≥3 parallel items.
+- Drop articles (a/an/the) in bullets, status lines, and headings if clarity is preserved. Keep them in full sentences.
+- No filler transitions ("Now,", "So,", "Basically,").
+- Limit tool-use meta-narration to ≤1 intent sentence.
+- Use arrow notation (`X → Y`) for causal chains.
+- For ambiguous intent: ask one short question, no preamble.
+
+### Example
+
+Verbose (reject):
+> Great question! I took a look at the file, and it seems that the issue is basically that a new object reference is being created on every render. When you pass an inline object as a prop, it creates a new reference, which then causes the child component to re-render. So, you'll want to wrap it in `useMemo` to fix this.
+
+Dense (accept):
+> Inline obj prop → new ref each render → child re-renders. Wrap in `useMemo`.
+
+## Drop dense mode for
+Revert to full prose when terseness risks harm or ambiguity:
+- Security warnings and threat-model explanations.
+- Confirmation prompts before irreversible or destructive actions (force push, `rm -rf`, dropping tables, deleting branches).
+- Multi-step sequences where fragment ordering or dropped articles could change the meaning or lead to misexecution.
+- When the user explicitly asks for clarification of something already stated tersely.
+
+## Override
+Honor per-turn verbose requests ("explain in detail", "walk me through"); revert next turn.

.claude/rules/10-java-standards.md

@@ -1,85 +1,30 @@
-# 10-java-standards.md
+# 10-java-standards.md — Hensu Java/Kotlin Invariants
 
-# Hensu Java & Kotlin Standards
+Generic SOLID/KISS/YAGNI/DRY apply silently. Only project-specific rules below.
 
-This document defines the strict coding standards for the Hensu engine. Adherence ensures
-**GraalVM native-image safety** and **multi-tenant isolation**.
+## Module boundaries
 
----
+- `hensu-core` has **zero third-party deps** beyond JDK 25. No vendor SDKs, no vendor `if/else`.
+- All `Agent` impls are interchangeable (Liskov). Capability differences go through narrow interfaces like `ToolCapable`, `Streamable` — never a God interface, never vendor-sniffing in the orchestration loop.
+- Shared constants/schema live in `hensu-core` so CLI and Server speak the same language.
+- Logic duplicated between `hensu-core` and `hensu-server` → extract to a shared util/base provider.
 
-## Engineering Philosophy (SOLID, KISS, YAGNI, DRY)
+## Concurrency
 
-You must justify every architectural change against these principles:
+- See `20-native-safety.md` §3 for the `ThreadLocal` ban and `ScopedValue` pattern.
+- Verify no data bleeds between parallel workflow nodes during fan-out/fan-in.
 
-### SOLID Protocol
+## Domain model
 
-* **S (Single Responsibility):** One class, one reason to change. Split executors from coordinators.
-* **O (Open/Closed):** Extend via interfaces. Do not modify the core orchestration loop for new providers.
-* **L (Liskov Substitution):** All `Agent` implementations must be interchangeable. No vendor-specific "if/else" logic
-  in the Core.
-* **I (Interface Segregation):** Favor many specific interfaces (e.g., `ToolCapable`, `Streamable`) over one "God"
-  interface.
-* **D (Dependency Inversion):** High-level logic must depend on abstractions. No direct dependencies on vendor SDKs in
-  `hensu-core`.
+- Domain results → `sealed interface` (e.g. `ExecutionResult`, `TransitionStatus`), consumed via `switch` pattern matching.
+- All domain models immutable; construct via `hensu-serialization` builder mixins.
 
-### KISS & YAGNI
+## Kotlin DSL
 
-* **Zero-Dependency Core:** No new libraries in `hensu-core` unless standard JVM (Java 25) is insufficient.
-* **Feature Restraint:** Do not build "future-proof" abstractions. Implement only what is required for the current
-  logic.
+- `@WorkflowDsl` (meta `@DslMarker`) on `WorkflowBuilder`, `GraphBuilder`, `NodeBuilder` — prevents scope leakage (an `agent { }` block must not see parent `node { }`).
 
-### DRY (Don't Repeat Yourself) & Single Source of Truth
+## Tests
 
-* **Logic Duplication:** If the same orchestration logic appears in both `hensu-core` and `hensu-server`, it must be
-  extracted into a shared internal utility or a base provider.
-* **Core Constants:** Do not hardcode strings for repeated constants. Use a shared `Constants` or `Schema` object
-  in the `core` module to ensure the CLI and Server speak the same language.
-* **The "Rule of Three":** Do not abstract code the first time it is repeated. Wait for the third occurrence to ensure
-  the abstraction is actually reusable and not a "leaky" coupling.
-* **SSOT (Single Source of Truth):** The `AGENTS.md` and the module rules are the SSOT for project intent.
-
----
-
-## Security: ScopedValues Over ThreadLocal
-
-To support high-concurrency Virtual Threads (Project Loom) and safe SaaS deployment, **`ScopedValues`** are mandatory
-for context propagation.
-
-* **RULE:** Never use `ThreadLocal`. It leads to memory leaks and context pollution in Virtual Thread pools.
-* **PATTERN:** Use `ScopedValue.where(CONTEXT, value).run(() -> { ... })` for passing tenant IDs, security tokens, and
-  workflow state.
-* **ISOLATION:** Rigorously verify that no data "bleeds" between workflow nodes during parallel execution.
-
----
-
-## Language Standards
-
-Hensu leverages the latest JVM features to reduce boilerplate and increase type safety.
-
-### **Java 25+ (Core & Server)**
-
-* **Sealed Hierarchies:** Use `sealed interface` for all domain results (e.g., `ExecutionResult`, `TransitionStatus`).
-* **Pattern Matching:** Use `switch` expression pattern matching for processing node types and workflow events.
-* **Immutability:** All domain models must be immutable. Use the builder pattern provided by the `hensu-serialization`
-  mixins.
-* **Try-With-Resources:** Always wrap AutoCloseable engine components in a try-with-resources block, even in tests, to
-  prevent memory leaks in the Virtual Thread carrier threads.
-
-### **Kotlin (DSL Layer)**
-
-* **DslMarker:** Define `@WorkflowDsl` (meta-annotated with `@DslMarker`) and apply it to all Builder classes.
-* **Scope Isolation:** This prevents **Scope Leakage**, ensuring that nested builders cannot access methods from parent
-  scopes incorrectly.
-    * *Example:* An `agent { ... }` block should not be able to call `node { ... }` from the parent graph.
-* **Builder Pattern:** Annotate `WorkflowBuilder`, `GraphBuilder`, and `NodeBuilder` with `@WorkflowDsl` to enforce this
-  boundary.
-* **Context Receivers:** Use context receivers where appropriate for cleaner DSL building logic.
-
----
-
-## Testing Integrity
-
-* **Unit Tests:** Must be pure JVM and use `StubAgentProvider` to avoid API costs and network latency.
-* **Integration Tests:** Use `@QuarkusTest` for server-side logic and verify native-image compatibility with
-  `-Dquarkus.native.enabled=true`.
-* **Assertions:** Use **AssertJ** for fluent, readable assertions.
+- Unit: pure JVM, `StubAgentProvider` only — no network, no API cost.
+- Integration: `@QuarkusTest`.
+- Assertions: AssertJ.