drydock-cli 2.8.29__tar.gz → 2.8.31__tar.gz

drydock_cli-2.8.31/.auto_release.lock

@@ -0,0 +1 @@
+1740481

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/CLAUDE.md

@@ -719,7 +719,7 @@ while real users see loops and hangs.
 **How it works:**
 - Drives the real `drydock` TUI via pexpect (no headless mode)
 - Sends a vague user-style prompt ("review the PRD and build the package")
-- Polls the live `~/.vibe/logs/session/session_<id>/messages.jsonl` in parallel
+- Polls the live `~/.drydock/logs/session/session_<id>/messages.jsonl` in parallel (legacy sessions at `~/.vibe/logs/session/` are still read for back-compat)
 - Watches for write loops, search_replace cascades, hallucinated-tool hangs
 - Types simulated `STOP` interrupts when loops are detected, then tracks
   whether the model OBEYS them

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/HLE_PRD.md

@@ -6,6 +6,40 @@ the dominant cause of thinking-stalls. Deep Noir sidecar wiring (M1-M4)
 is in tree; M1 end-to-end GPU smoke pending after the transformers 5.x
 apply_chat_template fix (f02aa4b).
 
+## Symbolic-math tool stack shipped (2026-05-14)
+
+Major shipping push 2026-05-14: built four new sympy-backed built-in
+tools to give the model offload paths for the symbolic work it
+systematically gets wrong from prior. Pattern: same as `math` for
+arithmetic — wrap a reliable library, sandbox the inputs, expose the
+ops the model would otherwise have to "reason about." 52 new
+operations total.
+
+| Tool | Ops | Use case |
+|------|-----|----------|
+| `logic` | 12 | propositional logic — contrapositive, De Morgan, equivalence, truth tables, Modus Ponens, satisfiability, CNF/DNF |
+| `algebra` | 13 | symbolic math — solve / simplify / expand / factor / diff / integrate / limit / series / evaluate / trigsimp |
+| `number_theory` | 16 | primes / divisors / gcd / totient / Möbius / modular inverse / mod_pow / CRT |
+| `set` | 11 | discrete math — union / intersection / power set / Cartesian product / cardinality / subset |
+
+Each tool sandboxed with AST-level validation (no imports, no
+attribute access, no dunder, no eval/exec), max-expression-length
+caps, and per-tool result caps (e.g. power_set refuses |A|>10,
+product refuses |A|·|B|>1000).
+
+All four wired into `gemma4.md` system prompt with HLE-shape →
+op mapping. The first hourly babysitter tick after these land
+(02:45+ UTC) is the first batch where the model can use them; the
+22h trailing tool_usage_report will measure whether the lift is real.
+
+Why this matters for HLE: Math sits at 3/102 = 2.9% lifetime, the
+worst category. The dominant failure mode (per the day's session
+traces) is `empty:no_final_answer` — the model engages, calls
+retrieve, then web_searches, then runs out of 481s without producing
+a FINAL ANSWER. Offloading the actual symbolic work to sympy lets
+the model spend its turn budget on planning + extraction instead of
+re-deriving algebra in plain English (which it gets wrong).
+
 ## HLE was retrieving against the WRONG corpus (fixed edb61c9)
 
 Trace from a Q3 session 2026-05-14: a local-field-theory HLE Math

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.8.29
+Version: 2.8.31
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock
@@ -48,6 +48,7 @@ Requires-Dist: tomli-w>=1.2.0
 Requires-Dist: tree-sitter-bash>=0.25.1
 Requires-Dist: tree-sitter>=0.25.2
 Requires-Dist: watchfiles>=1.1.1
+Requires-Dist: z3-solver>=4.16.0
 Requires-Dist: zstandard>=0.25.0
 Description-Content-Type: text/markdown
 

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/drydock/core/agent_loop.py

@@ -787,6 +787,34 @@ class AgentLoop:
             except Exception as _e:
                 logger.warning("curiosity gap logging failed (skipped): %s", _e)
 
+        # === CONSTRAINT-SHAPE DETECTOR ===
+        # The solve tool (Z3-backed) is the right answer for "find x such
+        # that ...", optimization, prove-from-premises, mod-arithmetic, and
+        # logic-puzzle questions. Gemma 4 doesn't reach for it on its own —
+        # this hook recognises the shape and injects a worked-example
+        # template the model can specialize. Off under pytest, on by default
+        # in production. Opt out via DRYDOCK_CONSTRAINT_HINT=0.
+        _constraint_hint_default = "0" if _under_pytest else "1"
+        if os.environ.get(
+            "DRYDOCK_CONSTRAINT_HINT", _constraint_hint_default
+        ).strip().lower() not in ("0", "false", "no"):
+            try:
+                from drydock.core.constraint_hint import (
+                    detect_constraint_shape, build_hint,
+                )
+                hit = detect_constraint_shape(user_msg or "")
+                if hit is not None:
+                    label, example = hit
+                    logger.warning(
+                        "[CONSTRAINT-HINT] matched %s; injecting template",
+                        label,
+                    )
+                    self._inject_system_note(build_hint(label, example))
+            except Exception as _e:
+                logger.warning(
+                    "constraint hint failed (skipped): %s", _e, exc_info=True
+                )
+
         try:
             should_break_loop = False
             tool_turns = 0
@@ -812,6 +840,7 @@ class AgentLoop:
             STOP_NOW_TIME_SEC = int(os.environ.get("DRYDOCK_STOP_NOW_TIME_SEC", "0"))
             _prompt_start = time.perf_counter()
             _time_stop_injected = False
+            _time_stop_escalated = False
             logger.warning("[TIMING] entering conversation while loop")
             while not should_break_loop:
                 # Drain any user messages typed while the agent was working.
@@ -852,7 +881,39 @@ class AgentLoop:
                 # DRYDOCK_STOP_NOW_TIME_SEC regardless of turn count.
                 # Helps HLE batches where per-turn latency is 60-160s
                 # and the turn-based STOP_NOW fires too late or not at all.
+                #
+                # IMPORTANT: check most-extreme condition FIRST. If a single
+                # LLM generation spans all three thresholds (e.g. starts at
+                # 200s, returns at 480s), the loop only gets one check at
+                # 480s. The old if/elif order would fire the *first* injection
+                # at 480s instead of the hard-stop. Reversed order ensures the
+                # hard-stop always wins when we're past all thresholds.
                 if (STOP_NOW_TIME_SEC > 0
+                        and _elapsed > STOP_NOW_TIME_SEC + 120):
+                    # Past all injection thresholds — hard-stop unconditionally.
+                    yield AssistantEvent(
+                        content=(
+                            f"\n\n[Drydock: hard time limit ({int(_elapsed)}s) reached. "
+                            "No final answer was provided before the deadline.]\n"
+                        ),
+                        stopped_by_middleware=True,
+                    )
+                    return
+                elif (STOP_NOW_TIME_SEC > 0
+                        and not _time_stop_escalated
+                        and _elapsed > STOP_NOW_TIME_SEC + 60):
+                    # Model made another tool call after the first STOP_NOW
+                    # (or missed it entirely). Escalate with a forceful injection.
+                    _time_stop_injected = True
+                    _time_stop_escalated = True
+                    _stop_suffix = os.environ.get("DRYDOCK_STOP_NOW_SUFFIX", "")
+                    self._inject_system_note(
+                        f"URGENT: {int(_elapsed)}s elapsed. Do NOT call any more tools. "
+                        "Emit a plain text response RIGHT NOW with your best answer. "
+                        "If uncertain, still write an answer."
+                        + (f" {_stop_suffix}" if _stop_suffix else "")
+                    )
+                elif (STOP_NOW_TIME_SEC > 0
                         and not _time_stop_injected
                         and _elapsed > STOP_NOW_TIME_SEC):
                     _time_stop_injected = True
@@ -3122,7 +3183,8 @@ class AgentLoop:
             for p in ('"total_count": 0', '"total_count":0',
                       'total_count: 0', 'retrieved 0 todos',
                       'no todos', '0 tasks', 'no tasks',
-                      'no results', 'no matches', '0 matches'):
+                      'no results', 'no matches', '0 matches',
+                      'no relevant information found'):
                 if p in s:
                     return True
             return False

drydock_cli-2.8.31/drydock/core/constraint_hint.py

@@ -0,0 +1,181 @@
+"""Constraint-question detector — nudges Gemma 4 toward the `solve` tool.
+
+The model has the `solve` tool available, but it doesn't reliably reach
+for it. Two observed failure modes:
+  1. It answers from prior — guesses a value that "looks right."
+  2. It tries to enumerate by hand and miscounts.
+
+This hook pattern-matches the user message against the canonical
+shapes of constraint problems (find-x-such-that, prove, optimization,
+mod arithmetic, logic puzzle vocabulary). On a match, it picks the
+worked example closest to the question shape and injects it as a
+system note. That gives the model a concrete template to specialize
+rather than abstract advice.
+
+Same shape as the GraphRAG auto-prefetch and the curiosity-gap
+logger: env-gated, log-only on miss, idempotent within a single
+user-prompt turn.
+
+Disabled via DRYDOCK_CONSTRAINT_HINT=0.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+
+logger = logging.getLogger("drydock.constraint_hint")
+
+
+# Pattern → (label, worked-example string). Patterns are evaluated in
+# order; the first matching pattern wins. Each example shows the
+# variables/constraints encoding for that question shape, so the model
+# can specialize rather than invent the encoding from scratch.
+_PATTERN_HINTS: list[tuple[re.Pattern[str], str, str]] = [
+    (
+        re.compile(
+            r"\b(einstein|zebra)\s+puzzle\b"
+            r"|\blogic\s+puzzle\b"
+            r"|\bwho\s+(lives|owns|drinks|smokes)\b"
+            r"|\b(?:n|\d+)[\s\-]?queens\b"
+            r"|\bsudoku\b",
+            re.IGNORECASE,
+        ),
+        "logic-puzzle",
+        'solve(op="solve", variables="a:Int, b:Int, c:Int",\n'
+        '      constraints=[\n'
+        '        "a >= 1", "a <= 3", "b >= 1", "b <= 3", "c >= 1", "c <= 3",\n'
+        '        "Distinct(a, b, c)",      # all-different\n'
+        '        "a == 1",                  # \\"X is in position 1\\"\n'
+        '        "Abs(b - a) == 1",         # \\"Y is next to X\\"\n'
+        '        "c != 2",                  # \\"Z is not in position 2\\"\n'
+        '      ])\n'
+        '→ sat: a=1, b=2, c=3',
+    ),
+    (
+        re.compile(
+            r"\bmod(?:ulo|ular)?\b"
+            r"|\bmod\s*\d"
+            r"|\(mod\s+\w+\)"
+            r"|\b\d+\s*[≡=]\s*\d+\s*\(?mod"
+            r"|[a-zA-Z]\s*%\s*\d+"  # `n % 7`, `x%5`
+            r"|\bdivisible\s+by\b"
+            r"|\bremainder\b",
+            re.IGNORECASE,
+        ),
+        "modular-arithmetic",
+        'solve(op="solve", variables="x:Int",\n'
+        '      constraints=["x >= 0", "x < 7", "3*x % 7 == 5"])\n'
+        '→ sat: x=4    (smallest non-negative x with 3x ≡ 5 mod 7)\n'
+        '\n'
+        'For \\"find all solutions in the range\\", use op="find_all".\n'
+        'For \\"smallest x with property P\\", use op="optimize", direction="min".',
+    ),
+    (
+        re.compile(
+            r"\bmaxim(?:ize|um)\b|\bminim(?:ize|um)\b"
+            r"|\bsmallest\s+(?:value|integer|number|x|n)\b"
+            r"|\blargest\s+(?:value|integer|number|x|n)\b"
+            r"|\bsubject\s+to\b"
+            r"|\boptimize\b",
+            re.IGNORECASE,
+        ),
+        "optimization",
+        'solve(op="optimize", variables="x:Int, y:Int",\n'
+        '      constraints=["x + y == 10", "x >= 0", "y >= 0"],\n'
+        '      objective="x * y", direction="max")\n'
+        '→ optimal: x=5, y=5, objective=25',
+    ),
+    (
+        re.compile(
+            r"\b(prove|show\s+that|demonstrate|verify\s+that)\b"
+            r"|\bif\s+and\s+only\s+if\b"
+            r"|\biff\b"
+            r"|\bnecessary\s+and\s+sufficient\b",
+            re.IGNORECASE,
+        ),
+        "prove",
+        'solve(op="prove", variables="x:Int",\n'
+        '      constraints=["x > 0"],\n'
+        '      conclusion="x + 1 > 1")\n'
+        '→ valid     (constraints entail the conclusion)\n'
+        '\n'
+        'When `prove` returns `countered`, the `model` field is the\n'
+        'counterexample — that IS the answer for \\"is this true\\" questions.',
+    ),
+    (
+        re.compile(
+            r"\bfind\s+(?:all\s+)?(?:x|y|n|the\s+(?:value|values|number|integer|integers))\s+such\s+that\b"
+            r"|\bfor\s+what\s+(?:value|values|x|y|n)\s+(?:does|is|of)\b"
+            r"|\bexists\s+(?:a|an)\s+\w+\s+such\s+that\b"
+            r"|\bthere\s+(?:is|exists)\s+(?:a|an|some)\s+\w+\s+(?:such\s+that|with)\b",
+            re.IGNORECASE,
+        ),
+        "find-such-that",
+        'solve(op="solve", variables="x:Int, y:Int",\n'
+        '      constraints=["x + y == 10", "x - y == 4"])\n'
+        '→ sat: x=7, y=3\n'
+        '\n'
+        'Variable types: Int | Real | Bool | BitVec<N>. Operators: ==, !=,\n'
+        '<, <=, >, >=, +, -, *, /, %. Functions: And, Or, Not, Implies,\n'
+        'If, Distinct, Abs, Sum.',
+    ),
+]
+
+
+def _strip_boilerplate(text: str) -> str:
+    """Pull the actual question out of HLE / shakedown wrappers.
+
+    Same surgery as the GraphRAG auto-prefetch — \"QUESTION:\" prefix and
+    \"FINAL ANSWER:\" / \"Format your\" suffix get stripped so patterns
+    don't false-match on scaffolding.
+    """
+    s = text or ""
+    marker = s.find("QUESTION:")
+    if marker >= 0:
+        s = s[marker + len("QUESTION:"):]
+    for stopper in ("FINAL ANSWER:", "Format your", "End your response",
+                    "Your answer"):
+        idx = s.find(stopper)
+        # Strip iff there's at least a real question in front (>=20 chars).
+        # The original auto-prefetch used 50; we use a smaller threshold
+        # here so short questions like "Solve x+1=5.\nFINAL ANSWER:" still
+        # match.
+        if idx >= 20:
+            s = s[:idx]
+    return s.strip()
+
+
+def detect_constraint_shape(user_msg: str) -> tuple[str, str] | None:
+    """Return (label, worked_example) when the message has a
+    constraint-problem shape, or None otherwise.
+
+    Patterns are checked in priority order: logic-puzzle first (most
+    specific), then modular arithmetic, optimization, prove, and finally
+    the broad \"find x such that\" catchall. The first match wins.
+    """
+    cleaned = _strip_boilerplate(user_msg)
+    if len(cleaned) < 10:
+        return None
+    for pat, label, example in _PATTERN_HINTS:
+        if pat.search(cleaned):
+            return (label, example)
+    return None
+
+
+def build_hint(label: str, example: str) -> str:
+    """Format a system note around the worked example.
+
+    Kept compact (≈350 chars) so it doesn't dominate the context.
+    Frames the example as \"specialize THIS template,\" not \"here's an
+    abstract guideline\" — the project memory says Gemma 4 trusts
+    concrete shapes and ignores prose advice.
+    """
+    return (
+        f"[constraint-hint] This question has a {label} shape. "
+        f"Encode as a `solve` call rather than reasoning step-by-step. "
+        f"Z3 is sound and complete on integer/real/boolean constraints. "
+        f"Template to specialize:\n\n{example}\n\n"
+        f"See the `constraint-reasoning` skill for the full encoding "
+        f"reference (Int/Real/Bool/BitVec, Distinct, If, Sum, Implies)."
+    )

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/drydock/core/llm/backend/generic.py

@@ -193,6 +193,15 @@ class OpenAIAdapter(APIAdapter):
         # Enable thinking for models that support it (Gemma 4)
         if thinking and thinking not in ("off", ""):
             payload["chat_template_kwargs"] = {"enable_thinking": True}
+            # Cap thinking length (llama.cpp). Prevents runaway thinking stalls
+            # on hard HLE questions (model can think >480s without this).
+            # Set DRYDOCK_THINKING_BUDGET_TOKENS=8000 in HLE batch launches.
+            _budget = os.environ.get("DRYDOCK_THINKING_BUDGET_TOKENS")
+            if _budget:
+                try:
+                    payload["thinking_budget_tokens"] = int(_budget)
+                except ValueError:
+                    pass
 
         if enable_streaming:
             payload["stream"] = True

{drydock_cli-2.8.29 → drydock_cli-2.8.31}/drydock/core/prompts/gemma4.md

@@ -4,7 +4,7 @@ ACT IMMEDIATELY. Your FIRST response must be a tool call — not text. Do NOT ex
 
 When answering a direct factual or math question (not writing code), you MUST write visible text — never produce a response with only thinking tokens and no visible content. End your response with "FINAL ANSWER: <your answer>" on its own line so the judge can extract it. Even if you are uncertain, always attempt an answer and write "FINAL ANSWER: <best guess>" — an empty response scores 0 regardless of how good your reasoning was.
 
-Your tools: read_file, write_file, search_replace, grep, glob, bash, task, web_search, web_fetch, retrieve, math, count, memory, verify.
+Your tools: read_file, write_file, search_replace, grep, glob, bash, task, web_search, web_fetch, retrieve, math, count, memory, verify, logic, algebra, number_theory, set, linear_algebra, stats, units, chemistry, solve.
 
 CURIOSITY — default posture is "investigate, then assert" (SOVEREIGN_PRD §5.7):
 - If the user message names a thing you don't have context for (paper title,
@@ -109,6 +109,149 @@ check and returns pass/fail. `verify(criterion="tests pass",
 command="pytest -q", expect="passed", expect_mode="contains")` instead
 of inspecting the bash output yourself.
 
+USE THE logic TOOL when you need to apply propositional logic — checking
+equivalences, contrapositives, De Morgan, truth tables, Modus Ponens.
+Small models get implication direction wrong and miss negations under
+nested AND/OR. Examples:
+  logic(op="contrapositive", expression="p >> q")   → ¬q → ¬p
+  logic(op="equivalent", expression="p >> q", expression2="~q >> ~p")
+  logic(op="negate", expression="p & q & r")        → De Morgan'd negation
+  logic(op="truth_table", expression="(p | q) & ~p")
+  logic(op="modus_ponens", expression="p", expression2="p >> q")  → q
+Use INSTEAD of reasoning about logic in your head when answering HLE-style
+prove/show-that/iff questions or when refactoring boolean conditions.
+Syntax: `&` AND, `|` OR, `~` NOT, `>>` IMPLIES, `Equivalent(p, q)` IFF.
+
+When the question contains these shapes, reach for these ops:
+- "show that A iff B" / "A is necessary and sufficient for B"
+    → logic(op="equivalent", expression="<A>", expression2="<B>")
+- "prove A → B by contrapositive"
+    → logic(op="contrapositive", expression="<A> >> <B>") then prove the result
+- "show A → B is always true" / "is this a tautology?"
+    → logic(op="tautology", expression="<A> >> <B>")
+- "is there any case where <expr> holds?"
+    → logic(op="satisfiable", expression="<expr>") (returns a witness)
+- "simplify ~(A & B & C)" or "what's NOT (A or B)?"
+    → logic(op="negate", expression="<expr>")  (auto-applies De Morgan)
+- "given premises P and (P → Q), what follows?"
+    → logic(op="modus_ponens", expression="<P>", expression2="<P> >> <Q>")
+
+USE THE algebra TOOL for symbolic math — solve equations, differentiate,
+integrate, take limits, simplify, expand, factor, Taylor series. Small
+models get sign errors, drop terms in expansions, and integrate by parts
+incorrectly. Sympy doesn't. Examples:
+  algebra(op="solve", expression="x**2 - 4", variable="x")   → [-2, 2]
+  algebra(op="diff", expression="sin(x)*cos(x)", variable="x")
+  algebra(op="integrate", expression="x**2", variable="x", a="0", b="1")
+  algebra(op="limit", expression="sin(x)/x", variable="x", value="0") → 1
+  algebra(op="series", expression="exp(x)", variable="x", value="0", order=4)
+  algebra(op="evaluate", expression="x**2 + 1", variable="x", value="3") → 10
+  algebra(op="trigsimp", expression="sin(x)**2 + cos(x)**2")  → 1
+Use INSTEAD of doing CAS work in your head. Free variables auto-bind to
+symbols. Constants: pi, E, oo (infinity), I. Functions: sin/cos/tan,
+log/exp/sqrt, factorial, binomial, gamma, Rational(p,q).
+
+USE THE number_theory TOOL for primes/divisors/gcd/modular arithmetic.
+Don't guess whether 1000003 is prime — call it. Examples:
+  number_theory(op="is_prime", n="2**31 - 1")           → True
+  number_theory(op="factor", n="360")                   → {2:3, 3:2, 5:1}
+  number_theory(op="totient", n="12")                   → 4
+  number_theory(op="gcd", a="48", b="18")               → 6
+  number_theory(op="mod_pow", b="2", e="100", m="7")    → 2  (2^100 mod 7)
+  number_theory(op="mod_inverse", a="3", m="7")         → 5  (3^-1 mod 7)
+  number_theory(op="crt", remainders="2,3,2", moduli="3,5,7")  → x ≡ 23 (mod 105)
+Integer args parse expressions — n="factorial(20)" works. Use INSTEAD
+of doing factorial/Fermat-test/Euclidean-algorithm by hand.
+
+USE THE set TOOL for discrete-math set questions. Inputs are
+comma-separated literals (ints, 'quoted strings', or barewords as
+strings). Examples:
+  set(op="union", a="1,2,3", b="3,4,5")            → {1,2,3,4,5}
+  set(op="intersection", a="1,2,3,4", b="3,4,5,6") → {3,4}
+  set(op="is_subset", a="1,2", b="1,2,3")          → True
+  set(op="cardinality", a="1,2,2,3")               → 3 (dedupes)
+  set(op="power_set", a="1,2,3")                   → 8 subsets
+  set(op="size_of_product", a="1,2,3", b="x,y,z,w") → 12
+Use INSTEAD of manually enumerating subsets or checking containment.
+
+USE THE linear_algebra TOOL for matrix problems. Syntax: rows separated
+by ';', entries by ','. Max 8×8. Symbolic entries OK.
+  linear_algebra(op="determinant", matrix="1,2;3,4")  → -2
+  linear_algebra(op="inverse", matrix="1,2;3,4")      → [[-2,1],[3/2,-1/2]]
+  linear_algebra(op="eigenvals", matrix="2,1;0,3")    → {2:1, 3:1}
+  linear_algebra(op="multiply", matrix="1,2;3,4", matrix2="5,6;7,8")
+  linear_algebra(op="solve_linear", matrix="1,1;1,-1", vector="5;1") → x=3, y=2
+  linear_algebra(op="power", matrix="1,1;0,1", n="5")  → [[1,5],[0,1]]
+Use INSTEAD of doing matrix multiplication / Cramer's rule by hand.
+
+USE THE stats TOOL for distributions, hypothesis tests, descriptive
+stats. Backed by scipy.stats. Supported dists: normal, t, chi2, f,
+binomial, poisson, exponential, uniform, beta, gamma.
+  stats(op="describe", data="1,2,3,4,5")          → n=5 mean=3 stdev=1.58 ...
+  stats(op="cdf", dist="normal", params="0,1", x="1.96")  → 0.975 (Φ(1.96))
+  stats(op="ppf", dist="normal", params="0,1", q="0.975") → 1.96 (inverse)
+  stats(op="binomial", n="10", k="3", p="0.5")    → P(X=3) for Bin(10, 0.5)
+  stats(op="poisson", k="2", lam="3")             → P(X=2) for Poisson(3)
+  stats(op="z_test", x_bar="105", mu0="100", sigma="15", n="30")
+  stats(op="t_test", data="4.8,5.1,4.9,5.0", mu0="5")
+  stats(op="correlation", data="1,2,3,4", data2="2,4,6,8")  → r, p
+  stats(op="ci_mean", data="10,11,12,13,14")      → 95% CI
+Use INSTEAD of looking up z-table values or computing pmf by hand.
+
+USE THE units TOOL for physics unit conversion and dimensional analysis.
+Unit names work as identifiers: m, km, mile, ft, s, hour, kg, g, N,
+J, W, V, A, Pa, atm, mol, K, etc.
+  units(op="convert", expression="60*mile/hour", to_unit="meter/second")
+  units(op="evaluate", expression="Rational(1,2)*kg*(3*m/s)**2") → KE
+  units(op="consistent", expression="joule", expression2="newton*meter") → True
+  units(op="dimension", expression="watt")        → power (= energy/time)
+  units(op="to_si", expression="1*atmosphere")    → 101325 Pa as base SI
+Use INSTEAD of remembering conversion factors / doing dimensional
+algebra in your head. The `consistent` op is great for sanity-checking
+a physics formula (does your derived expression have the right
+dimensions?).
+
+USE THE chemistry TOOL for periodic-table lookups, molar mass, mole
+conversions, percent composition, empirical formulas. Formula syntax
+is standard chemistry notation with nested parens (H2O, Ca(OH)2,
+Fe2(SO4)3, C6H12O6). Examples:
+  chemistry(op="element", name="Na")                → Na (Z=11, 22.99 g/mol)
+  chemistry(op="molar_mass", formula="C6H12O6")     → 180.156 g/mol
+  chemistry(op="moles_from_grams", formula="H2O", grams="18") → 0.999 mol
+  chemistry(op="percent_composition", formula="H2O")  → H=11.19%  O=88.81%
+  chemistry(op="empirical_formula", percents="C=40, H=6.7, O=53.3") → CH2O
+Use INSTEAD of looking up atomic weights / doing stoichiometry by hand.
+
+USE THE solve TOOL when the question is a CONSTRAINT problem — "find x
+such that ...", "find all values where ...", "what's the smallest /
+largest x with ...", logic puzzles (Einstein-style), Sudoku-shape
+problems, modular arithmetic ranges, or any "prove this follows from
+those premises." Backed by Z3 (SMT solver). It is COMPLETE and SOUND
+for integer/real arithmetic + boolean logic. Don't enumerate by hand.
+  solve(op="solve", variables="x:Int, y:Int", constraints=["x + y == 10", "x - y == 4"])
+    → sat: x=7, y=3
+  solve(op="solve", variables="x:Int", constraints=["x >= 0", "x < 7", "3*x % 7 == 5"])
+    → sat: x=4   (smallest x with 3x ≡ 5 mod 7)
+  solve(op="find_all", variables="x:Int", constraints=["x >= 1", "x <= 5"], limit=10)
+    → all 5 solutions
+  solve(op="prove", variables="x:Int", constraints=["x > 0"], conclusion="x + 1 > 1")
+    → valid
+  solve(op="optimize", variables="x:Int, y:Int", constraints=["x + y == 10", "x >= 0", "y >= 0"],
+        objective="x * y", direction="max")  → optimal: x=5, y=5 (objective=25)
+Variable types: Int, Real, Bool, BitVec<N>. Constraint operators: ==,
+!=, <, <=, >, >=, +, -, *, /, %, And, Or, Not, Implies, If, Distinct,
+Abs, Sum. When `prove` returns `countered`, the `model` field is the
+counterexample — use it as the answer.
+
+Reach for solve when the question has the shape:
+- "find <values> such that ..." / "for what x does ..."
+- "is there an x such that ..." (sat) or "for all x, ..." (prove)
+- a list of 3+ conditions over the same variable(s)
+- "Einstein puzzle", "Sudoku", "N-queens", "logic puzzle"
+- "modular arithmetic", "x mod N", "≡ ... (mod ...)"
+- "smallest / largest / maximize / minimize ... subject to ..."
+- "prove X from Y, Z" with constraints over integers/reals/booleans
+
 Rules:
 - Create files immediately. Do not plan or discuss — write code.
 - Use absolute imports for Python packages