invar-tools 1.7.1__py3-none-any.whl → 1.10.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

@@ -0,0 +1,256 @@
+<!--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 -%}
+{% 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)
+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)
+```
+{% 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-->
+
+<!--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.
+
+---
+
+## 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.
+{% endif %}
+
+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).
+
+## Quick Reference
+
+| 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)
+
+- 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) |
+| AGENT.md | User | Yes | Project customization (this file) |
+| .invar/context.md | User | Yes | Project state, lessons learned |
+| .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
+
+> **Before writing code:** Check Task Router in `.invar/context.md`
+
+## USBV Workflow
+
+For complex tasks (3+ functions), follow these phases:
+
+### 1. UNDERSTAND
+
+- **Intent:** What exactly needs to be done?
+{% if syntax == "mcp" -%}
+- **Inspect:** Use `invar_sig` to see existing contracts
+{% else -%}
+- **Inspect:** Use `invar sig` to see existing contracts
+{% endif -%}
+- **Context:** Read relevant code, understand patterns
+- **Constraints:** What must NOT change?
+
+### 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)
+@post(lambda result: result >= 0)
+def calculate(x: int) -> int:
+    """
+    >>> calculate(10)
+    100
+    """
+    ...  # 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
+
+- Follow the contracts written in SPECIFY
+{% if syntax == "mcp" -%}
+- Run `invar_guard(changed=true)` frequently
+{% else -%}
+- Run `invar guard --changed` frequently
+{% endif -%}
+- Commit after each logical unit
+
+### 4. VALIDATE
+
+{% if syntax == "mcp" -%}
+- Run `invar_guard()` (full verification)
+{% else -%}
+- Run `invar guard` (full verification)
+{% endif -%}
+- Integration works (if applicable)
+
+---
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See contracts | `invar_sig(target="<file>")` |
+| Find entry points | `invar_map(top=10)` |
+| Verify code | `invar_guard()` |
+{% else -%}
+| See contracts | `invar sig <file>` |
+| Find entry points | `invar map --top 10` |
+| Verify code | `invar guard` |
+{% endif -%}
+
+---
+
+## Task Completion
+
+A task is complete only when ALL conditions are met:
+- Check-In displayed: `✓ Check-In: [project] | [branch] | [clean/dirty]`
+- Intent explicitly stated
+- Contract written before implementation
+- Final displayed: `✓ Final: guard PASS | <errors>, <warnings>`
+- User requirement satisfied
+
+**Missing any = Task incomplete.**
+
+<!--/invar:managed-->
+<!--invar:project-->
+<!--/invar:project-->
+<!--invar:user-->
+<!-- ========================================================================
+     USER REGION - EDITABLE
+     Add your team conventions and project-specific rules below.
+     This section is preserved across `invar update` and `invar dev sync`.
+     ======================================================================== -->
+<!--/invar:user-->
+
+---
+
+*Generated by `invar init` v{{ version }}. Customize the user section freely.*

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"]