invar-tools 1.8.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

invar/templates/claude-md/universal/workflow.md

@@ -0,0 +1,55 @@
+## Documentation Structure
+
+| File | Owner | Edit? | Purpose |
+|------|-------|-------|---------|
+| INVAR.md | Invar | No | Protocol (`invar update` to sync) |
+| CLAUDE.md | User | Yes | Project customization (this file) |
+| .invar/context.md | User | Yes | Project state, lessons learned |
+| .invar/project-additions.md | User | Yes | Project rules → injected into CLAUDE.md |
+| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
+
+> **Before writing code:** Check Task Router in `.invar/context.md`
+
+## Visible Workflow (DX-30)
+
+For complex tasks (3+ functions), show 3 checkpoints in TodoList:
+
+```
+□ [UNDERSTAND] Task description, codebase context, constraints
+□ [SPECIFY] Contracts and design decomposition
+□ [VALIDATE] Guard results, Review Gate status, integration status
+```
+
+**BUILD is internal work** — not shown in TodoList.
+
+**Show contracts before code.** See `.invar/examples/workflow.md` for full example.
+
+## Phase Visibility (DX-51)
+
+Each USBV phase transition requires a visible header:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Three-layer visibility:**
+- **Skill** (`/develop`) — Routing announcement
+- **Phase** (`SPECIFY 2/4`) — Phase header (this section)
+- **Tasks** — TodoWrite items
+
+Phase headers are SEPARATE from TodoWrite. Phase = where you are; TodoWrite = what to do.
+
+---
+
+## Context Management (DX-54)
+
+Re-read `.invar/context.md` when:
+1. Entering any workflow (/develop, /review, etc.)
+2. Completing a TodoWrite task (before moving to next)
+3. Conversation exceeds ~15-20 exchanges
+4. Unsure about project rules or patterns
+
+**Refresh is transparent** — do not announce "I'm refreshing context."
+Only show routing announcements when entering workflows.

invar/templates/commands/{audit.md → audit.md.jinja}

@@ -1,6 +1,6 @@
 ---
 _invar:
-  version: "5.0"
+  version: "{{ version }}"
   type: command
 ---
 
@@ -51,12 +51,21 @@ You ARE here to:
 > **Principle:** Only items requiring semantic judgment. Mechanical checks are excluded (see bottom).
 
 ### A. Contract Semantic Value
+{% if language == "python" %}
 - [ ] Does @pre constrain inputs beyond type checking?
   - Bad: `@pre(lambda x: isinstance(x, int))`
   - Good: `@pre(lambda x: x > 0 and x < MAX_VALUE)`
 - [ ] Does @post verify meaningful output properties?
   - Bad: `@post(lambda result: result is not None)`
   - Good: `@post(lambda result: len(result) == len(input))`
+{% elif language == "typescript" %}
+- [ ] Does Zod schema constrain inputs beyond type checking?
+  - Bad: `z.number()` (type only)
+  - Good: `z.number().positive().max(MAX_VALUE)` (semantic constraints)
+- [ ] Does output schema verify meaningful properties?
+  - Bad: `z.string()` (type only)
+  - Good: `z.string().min(1).max(100)` (semantic constraints)
+{% endif %}
 - [ ] Could someone implement correctly from contracts alone?
 - [ ] Are boundary conditions explicit in contracts?
 
@@ -100,7 +109,11 @@ You ARE here to:
 
 These are checked by Guard or linters - don't duplicate:
 - Core/Shell separation → Guard (forbidden_import, impure_call)
+{% if language == "python" -%}
 - Shell returns Result[T,E] → Guard (shell_result)
+{% elif language == "typescript" -%}
+- Shell returns Result<T,E> → Guard (shell_result)
+{% endif -%}
 - Missing contracts → Guard (missing_contract)
 - File/function size limits → Guard (file_size, function_size)
 - Entry point thickness → Guard (entry_point_too_thick)
@@ -121,7 +134,11 @@ For each issue found, use severity levels:
 ```markdown
 ### [CRITICAL/MAJOR/MINOR] Issue Title
 
+{% if language == "python" -%}
 **Location:** file.py:line_number
+{% elif language == "typescript" -%}
+**Location:** file.ts:line_number
+{% endif -%}
 **Category:** contract_quality | logic_error | security | escape_hatch | code_smell
 **Problem:** What's wrong
 **Suggestion:** How to fix (but don't implement)

invar/templates/config/AGENT.md.jinja

@@ -8,12 +8,18 @@
 {% else -%}
 | **Verify** | `invar guard` — NOT pytest, NOT crosshair |
 {% endif -%}
+{% if language == "python" -%}
 | **Core** | `@pre/@post` + doctests, NO I/O imports |
 | **Shell** | Returns `Result[T, E]` from `returns` library |
+{% elif language == "typescript" -%}
+| **Core** | Zod schemas + JSDoc examples, NO I/O imports |
+| **Shell** | Returns `Result<T, E>` from `neverthrow` library |
+{% endif -%}
 | **Flow** | USBV: Understand → Specify → Build → Validate |
 
 ### Contract Rules (CRITICAL)
 
+{% if language == "python" -%}
 ```python
 # ❌ WRONG: Lambda must include ALL parameters
 @pre(lambda x: x >= 0)
@@ -29,6 +35,21 @@ def calc(x: int, y: int = 0): ...
 # ✅ CORRECT: @post only sees 'result'
 @post(lambda result: result >= 0)
 ```
+{% elif language == "typescript" -%}
+```typescript
+// ❌ WRONG: Type-only validation (no semantic value)
+const Input = z.number();
+
+// ✅ CORRECT: Semantic constraints
+const Input = z.number().nonnegative().max(100);
+
+// ❌ WRONG: Output schema cannot reference input
+const Output = z.number().min(x);  // 'x' not available!
+
+// ✅ CORRECT: Output schema only validates result
+const Output = z.number().nonnegative();
+```
+{% endif -%}
 
 <!--/invar:critical-->
 
@@ -67,11 +88,19 @@ This is your sign-out. Completes the Check-In/Final pair.
 
 ## Project Structure
 
+{% if language == "python" -%}
 ```
 src/{project}/
 ├── core/    # Pure logic (@pre/@post, doctests, no I/O)
 └── shell/   # I/O operations (Result[T, E] return type)
 ```
+{% elif language == "typescript" -%}
+```
+src/
+├── core/    # Pure logic (Zod schemas, JSDoc examples, no I/O)
+└── shell/   # I/O operations (Result<T, E> return type)
+```
+{% endif -%}
 
 **Key insight:** Core receives data (strings), Shell handles I/O (paths, files).
 
@@ -79,8 +108,13 @@ src/{project}/
 
 | Zone | Requirements |
 |------|-------------|
+{% if language == "python" -%}
 | Core | `@pre`/`@post` + doctests, pure (no I/O) |
 | Shell | Returns `Result[T, E]` from `returns` library |
+{% elif language == "typescript" -%}
+| Core | Zod schemas + JSDoc examples, pure (no I/O) |
+| Shell | Returns `Result<T, E>` from `neverthrow` library |
+{% endif -%}
 
 ### Core vs Shell (Edge Cases)
 
@@ -118,10 +152,16 @@ For complex tasks (3+ functions), follow these phases:
 
 ### 2. SPECIFY
 
+{% if language == "python" -%}
 - **Contracts FIRST:** Write `@pre`/`@post` before implementation
 - **Doctests:** Add examples for expected behavior
+{% elif language == "typescript" -%}
+- **Contracts FIRST:** Write Zod schemas before implementation
+- **JSDoc Examples:** Add `@example` for expected behavior
+{% endif -%}
 - **Design:** Decompose complex tasks into sub-functions
 
+{% if language == "python" -%}
 ```python
 # SPECIFY before BUILD:
 @pre(lambda x: x > 0)
@@ -133,6 +173,24 @@ def calculate(x: int) -> int:
     """
     ...  # Implementation comes in BUILD
 ```
+{% elif language == "typescript" -%}
+```typescript
+// SPECIFY before BUILD:
+import { z } from 'zod';
+
+const CalculateInput = z.number().positive();
+const CalculateOutput = z.number().nonnegative();
+
+/**
+ * @example calculate(10) // => 100
+ */
+function calculate(x: number): number {
+    const validated = CalculateInput.parse(x);
+    // Implementation comes in BUILD
+    return CalculateOutput.parse(result);
+}
+```
+{% endif -%}
 
 ### 3. BUILD
 

invar/templates/config/CLAUDE.md.jinja

@@ -1,226 +1,33 @@
-<!--invar:critical-->
-## ⚡ Critical Rules
-
-| Always | Remember |
-|--------|----------|
-{% if syntax == "mcp" -%}
-| **Verify** | `invar_guard` — NOT pytest, NOT crosshair |
-{% else -%}
-| **Verify** | `invar guard` — NOT pytest, NOT crosshair |
-{% endif -%}
-| **Core** | `@pre/@post` + doctests, NO I/O imports |
-| **Shell** | Returns `Result[T, E]` from `returns` library |
-| **Flow** | USBV: Understand → Specify → Build → Validate |
-
-### Contract Rules (CRITICAL)
-
-```python
-# ❌ WRONG: Lambda must include ALL parameters
-@pre(lambda x: x >= 0)
-def calc(x: int, y: int = 0): ...
-
-# ✅ CORRECT: Include defaults too
-@pre(lambda x, y=0: x >= 0)
-def calc(x: int, y: int = 0): ...
-
-# ❌ WRONG: @post cannot access parameters
-@post(lambda result: result > x)  # 'x' not available!
-
-# ✅ CORRECT: @post only sees 'result'
-@post(lambda result: result >= 0)
-```
-
-<!--/invar:critical-->
+{# CLAUDE.md Composition Template
+   Composes universal workflow + language-specific rules
+   Variables: language (python|typescript), syntax (mcp|cli), version
+#}
+{% if language == "python" %}
+{% include "claude-md/python/critical-rules.md" %}
+{% elif language == "typescript" %}
+{% include "claude-md/typescript/critical-rules.md" %}
+{% endif %}
 
 <!--invar:managed version="{{ version }}"-->
 # Project Development Guide
 
 > **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
 
-## Check-In
-
-> See [INVAR.md#check-in](./INVAR.md#check-in-required) for full protocol.
-
-**Your first message MUST display:** `✓ Check-In: [project] | [branch] | [clean/dirty]`
-
-**Actions:** Read `.invar/context.md`, then show status. Do NOT run guard at Check-In.
+{% include "claude-md/universal/check-in.md" %}
 
 ---
 
-## Final
-
-Your last message for an implementation task MUST display:
-
-```
-✓ Final: guard PASS | 0 errors, 2 warnings
-```
-
-{% if syntax == "mcp" -%}
-Execute `invar_guard()` and show this one-line summary.
-{% else -%}
-Execute `invar guard` and show this one-line summary.
+{% if language == "python" %}
+{% include "claude-md/python/quick-reference.md" %}
+{% elif language == "typescript" %}
+{% include "claude-md/typescript/quick-reference.md" %}
 {% endif %}
 
-This is your sign-out. Completes the Check-In/Final pair.
+{% include "claude-md/universal/workflow.md" %}
 
 ---
 
-## Project Structure
-
-```
-src/{project}/
-├── core/    # Pure logic (@pre/@post, doctests, no I/O)
-└── shell/   # I/O operations (Result[T, E] return type)
-```
-
-**Key insight:** Core receives data (strings), Shell handles I/O (paths, files).
-
-## Quick Reference
-
-| Zone | Requirements |
-|------|-------------|
-| Core | `@pre`/`@post` + doctests, pure (no I/O) |
-| Shell | Returns `Result[T, E]` from `returns` library |
-
-### Core vs Shell (Edge Cases)
-
-- File/network/env vars → **Shell**
-- `datetime.now()`, `random` → **Inject param** OR Shell
-- Pure logic → **Core**
-
-> Full decision tree: [INVAR.md#core-shell](./INVAR.md#decision-tree-core-vs-shell)
-
-## Documentation Structure
-
-| File | Owner | Edit? | Purpose |
-|------|-------|-------|---------|
-| INVAR.md | Invar | No | Protocol (`invar update` to sync) |
-| CLAUDE.md | User | Yes | Project customization (this file) |
-| .invar/context.md | User | Yes | Project state, lessons learned |
-| .invar/project-additions.md | User | Yes | Project rules → injected into CLAUDE.md |
-| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
-
-> **Before writing code:** Check Task Router in `.invar/context.md`
-
-## Visible Workflow (DX-30)
-
-For complex tasks (3+ functions), show 3 checkpoints in TodoList:
-
-```
-□ [UNDERSTAND] Task description, codebase context, constraints
-□ [SPECIFY] Contracts (@pre/@post) and design decomposition
-□ [VALIDATE] Guard results, Review Gate status, integration status
-```
-
-**BUILD is internal work** — not shown in TodoList.
-
-**Show contracts before code.** See `.invar/examples/workflow.md` for full example.
-
-## Phase Visibility (DX-51)
-
-Each USBV phase transition requires a visible header:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📍 /develop → SPECIFY (2/4)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Three-layer visibility:**
-- **Skill** (`/develop`) — Routing announcement
-- **Phase** (`SPECIFY 2/4`) — Phase header (this section)
-- **Tasks** — TodoWrite items
-
-Phase headers are SEPARATE from TodoWrite. Phase = where you are; TodoWrite = what to do.
-
----
-
-## Context Management (DX-54)
-
-Re-read `.invar/context.md` when:
-1. Entering any workflow (/develop, /review, etc.)
-2. Completing a TodoWrite task (before moving to next)
-3. Conversation exceeds ~15-20 exchanges
-4. Unsure about project rules or patterns
-
-**Refresh is transparent** — do not announce "I'm refreshing context."
-Only show routing announcements when entering workflows.
-
----
-
-## Commands (User-Invokable)
-
-| Command | Purpose |
-|---------|---------|
-| `/audit` | Read-only code review (reports issues, no fixes) |
-| `/guard` | Run Invar verification (reports results) |
-
-## Skills (Agent-Invoked)
-
-| Skill | Triggers | Purpose |
-|-------|----------|---------|
-| `/investigate` | "why", "explain", vague tasks | Research mode, no code changes |
-| `/propose` | "should we", "compare" | Decision facilitation |
-| `/develop` | "add", "fix", "implement" | USBV implementation workflow |
-| `/review` | After /develop, `review_suggested` | Adversarial review with fix loop |
-
-**Note:** Skills are invoked by agent based on context. Use `/audit` for user-initiated review.
-
-Guard triggers `review_suggested` for: security-sensitive files, escape hatches >= 3, contract coverage < 50%.
-
----
-
-## Workflow Routing (MANDATORY)
-
-When user message contains these triggers, you MUST use the **Skill tool** to invoke the skill:
-
-| Trigger Words | Skill Tool Call | Notes |
-|---------------|-----------------|-------|
-| "review", "review and fix" | `Skill(skill="review")` | Adversarial review with fix loop |
-| "implement", "add", "fix", "update" | `Skill(skill="develop")` | Unless in review context |
-| "why", "explain", "investigate" | `Skill(skill="investigate")` | Research mode, no code changes |
-| "compare", "should we", "design" | `Skill(skill="propose")` | Decision facilitation |
-
-**⚠️ CRITICAL: You must call the Skill tool, not just follow the workflow mentally.**
-
-The Skill tool reads `.claude/skills/<skill>/SKILL.md` which contains:
-- Detailed phase instructions (USBV breakdown)
-- Error handling rules
-- Timeout policies
-- Incremental development patterns (DX-63)
-
-**Violation check (before writing ANY code):**
-- "Did I call `Skill(skill="...")`?"
-- "Am I following the SKILL.md instructions?"
-
----
-
-## Routing Control (DX-42)
-
-Agent announces routing decision before entering any workflow:
-
-```
-📍 Routing: /[skill] — [trigger or reason]
-   Task: [summary]
-```
-
-**User can redirect with natural language:**
-- "wait" / "stop" — pause and ask for direction
-- "just do it" — proceed with /develop
-- "let's discuss" — switch to /propose
-- "explain first" — switch to /investigate
-
-**Simple task optimization:** For simple tasks (single file, clear target, <50 lines), agent may offer:
-
-```
-📊 Simple task. Auto-orchestrate? [Y/N]
-```
-
-- Y → Full cycle without intermediate confirmations
-- N → Normal step-by-step workflow
-
-**Auto-review (DX-41):** When Guard outputs `review_suggested`, agent automatically
-enters /review. Say "skip" to bypass.
+{% include "claude-md/universal/skills.md" %}
 <!--/invar:managed-->
 
 <!--invar:project-->

invar/templates/config/context.md.jinja

@@ -13,8 +13,13 @@
 <!-- DX-54: Rules summary for long conversation resilience -->
 
 ### Core/Shell Separation
+{% if language == "python" -%}
 - **Core** (`**/core/**`): @pre/@post + doctests, NO I/O imports
 - **Shell** (`**/shell/**`): Result[T, E] return type
+{% elif language == "typescript" -%}
+- **Core** (`**/core/**`): Contract comments (@pre/@post), no side effects
+- **Shell** (`**/shell/**`): Result<T, E> return type
+{% endif -%}
 
 ### USBV Workflow
 1. Understand → 2. Specify (contracts first) → 3. Build → 4. Validate
@@ -31,6 +36,7 @@
 
 <!-- Before writing code, check this table -->
 
+{% if language == "python" %}
 | If you are about to... | STOP and read first |
 |------------------------|---------------------|
 | Write code in `core/` | `.invar/examples/contracts.py` |
@@ -38,6 +44,15 @@
 | Add `@pre`/`@post` contracts | `.invar/examples/contracts.py` |
 | Use functional patterns | `.invar/examples/functional.py` |
 | Implement a feature | `.invar/examples/workflow.md` |
+{% elif language == "typescript" %}
+| If you are about to... | STOP and read first |
+|------------------------|---------------------|
+| Write code in `core/` | `.invar/examples/contracts.ts` |
+| Write code in `shell/` | `.invar/examples/core_shell.ts` |
+| Add contract comments | `.invar/examples/contracts.ts` |
+| Use functional patterns | `.invar/examples/functional.ts` |
+| Implement a feature | `.invar/examples/workflow.md` |
+{% endif %}
 
 **Rule:** Match found above? Read the file BEFORE writing code.
 
@@ -53,7 +68,11 @@
 
 **Quick rule check:**
 - Am I in Core or Shell?
+{% if language == "python" -%}
 - Do I have @pre/@post contracts?
+{% elif language == "typescript" -%}
+- Do I have contract comments (@pre/@post)?
+{% endif -%}
 - Am I following USBV workflow?
 - Did I run guard before claiming "done"?
 

invar/templates/examples/{README.md → python/README.md}

@@ -8,6 +8,7 @@ Reference examples for the Invar Protocol. These are managed by Invar.
 |------|---------|
 | [contracts.py](contracts.py) | @pre/@post patterns, doctest best practices |
 | [core_shell.py](core_shell.py) | Core/Shell separation patterns |
+| [functional.py](functional.py) | Functional patterns (NewType, Validation, NonEmpty, Literal) |
 | [workflow.md](workflow.md) | Visible USBV workflow example |
 
 ## Usage
@@ -16,6 +17,7 @@ Read these when you need:
 - Contract pattern reference
 - Core vs Shell decision guidance
 - Doctest formatting examples
+- Functional pattern suggestions
 - USBV workflow example
 
 ---

invar/templates/examples/{conftest.py → python/conftest.py}

@@ -1,3 +1,3 @@
 # Skip pytest collection for example files
 # These are reference examples, not tests.
-collect_ignore = ["contracts.py", "core_shell.py", "workflow.md"]
+collect_ignore = ["contracts.py", "core_shell.py", "functional.py", "workflow.md"]

invar/templates/examples/{contracts.py → python/contracts.py}

@@ -1,13 +1,14 @@
+# ruff: noqa: ERA001
 """
 Invar Contract Examples
 
 Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
+# @invar:allow partial_contract: Educational file showing multiple @pre pattern
 
-# For lambda-based contracts, use deal directly
-# invar_runtime.pre/post are for Contract objects (NonEmpty, IsInstance, etc.)
-from deal import post, pre
+# invar_runtime supports both lambda and Contract objects
+from invar_runtime import post, pre
 
 # =============================================================================
 # GOOD: Complete Contract
@@ -80,7 +81,7 @@ def normalize_keys(data: dict[str, int]) -> dict[str, int]:
 # DON'T: Empty contract tells nothing
 # @pre(lambda: True)
 # @post(lambda result: True)
-# def process(x): ...  # noqa: ERA001
+# def process(x): ...
 
 # DON'T: Missing edge cases in doctests
 # def divide(a, b):
@@ -111,3 +112,79 @@ def range_size(start: int, end: int) -> int:
     1
     """
     return end - start
+
+
+# =============================================================================
+# CRITICAL: Default Parameters in Contracts
+# =============================================================================
+# Lambda signatures MUST include ALL parameters, including defaults!
+# This is a common mistake that causes silent contract failures.
+
+
+# DON'T: Missing default parameter in lambda
+# @pre(lambda x: x >= 0)  # BAD: 'y' is missing!
+# def calc_bad(x: int, y: int = 0) -> int:
+#     return x + y
+
+
+# DO: Include all parameters with their defaults
+@pre(lambda x, y=0: x >= 0 and y >= 0)
+@post(lambda result: result >= 0)
+def calculate_with_default(x: int, y: int = 0) -> int:
+    """
+    Calculate sum with optional y.
+
+    The lambda MUST include y=0 to match the function signature.
+
+    >>> calculate_with_default(5)
+    5
+    >>> calculate_with_default(5, 3)
+    8
+    >>> calculate_with_default(0, 0)  # Edge: both zero
+    0
+    """
+    return x + y
+
+
+# =============================================================================
+# CRITICAL: @post Cannot Access Parameters
+# =============================================================================
+# @post only receives the return value, not the original parameters!
+
+
+# DON'T: Reference parameters in @post
+# @post(lambda result: result > x)  # BAD: 'x' is not available!
+# def double_bad(x: int) -> int:
+#     return x * 2
+
+
+# DO: @post only validates the result itself
+@pre(lambda x: x >= 0)
+@post(lambda result: result >= 0)  # GOOD: only uses 'result'
+def double_positive(x: int) -> int:
+    """
+    Double a positive number.
+
+    @post can only validate result properties, not relationships to inputs.
+
+    >>> double_positive(5)
+    10
+    >>> double_positive(0)  # Edge: zero
+    0
+    """
+    return x * 2
+
+
+# =============================================================================
+# Decorator Order with @pre/@post
+# =============================================================================
+# When combining with other decorators, @pre/@post should be closest to function.
+
+
+# DO: @pre/@post closest to function
+# @other_decorator
+# @pre(lambda x: x > 0)
+# @post(lambda result: result > 0)
+# def my_func(x: int) -> int: ...
+
+# This ensures contracts run BEFORE other decorators modify behavior.