invar-tools 1.5.0__tar.gz → 1.7.0__tar.gz

{invar_tools-1.5.0 → invar_tools-1.7.0}/.claude/skills/develop/SKILL.md

@@ -17,7 +17,8 @@ _invar:
 
 Before any workflow action:
 1. Read `.invar/context.md` (especially Key Rules section)
-2. Display routing announcement
+2. **Check Task Router** — read examples before coding in `core/` or `shell/`
+3. Display routing announcement
 
 ### Routing Announcement
 

{invar_tools-1.5.0 → invar_tools-1.7.0}/.invar/context.md

@@ -19,6 +19,18 @@
 - `invar_guard()` = static + doctests + CrossHair + Hypothesis
 - Final must show: `✓ Final: guard PASS | ...`
 
+## Task Router (DX-62)
+
+| If you are about to... | STOP and read first |
+|------------------------|---------------------|
+| Write code in `core/` | `.invar/examples/contracts.py` |
+| Write code in `shell/` | `.invar/examples/core_shell.py` |
+| Add `@pre`/`@post` contracts | `.invar/examples/contracts.py` |
+| Use functional patterns | `.invar/examples/functional.py` |
+| Implement a feature | `.invar/examples/workflow.md` |
+
+**Rule:** Match found above? Read the file BEFORE writing code.
+
 ## Self-Reminder
 
 <!-- DX-54: AI should re-read this file periodically -->
@@ -136,12 +148,13 @@ gh release create vX.Y.Z --title "vX.Y.Z - Title" --notes "..."
 
 | File | Owner | Edit? |
 |------|-------|-------|
-| INVAR.md | **Source** | Yes (this IS the source) |
-| CLAUDE.md | User | Yes |
+| src/invar/templates/ | **SSOT** | Yes (templates are source) |
+| INVAR.md | Sync | No (`invar dev sync`) |
+| CLAUDE.md | Sync + User | Regions only |
 | .invar/context.md | User | Yes (this file) |
-| .invar/examples/ | Sync | `invar update --force` |
+| .invar/examples/ | Sync | `invar dev sync` |
 
-**Note:** This is the Invar project. INVAR.md is the **source**, not a copy.
+**Version Flow:** `templates/` → Invar project (via `invar dev sync`, syntax=mcp) AND → User projects (via `invar init/update`, syntax=cli)
 
 ---
 

{invar_tools-1.5.0 → invar_tools-1.7.0}/.invar/examples/workflow.md

@@ -136,6 +136,105 @@ Code Health: 100%
 # If triggered: invoke /review sub-agent before completion
 ```
 
+## Interleaved SPECIFY/BUILD (DX-63)
+
+For multi-function tasks, use **interleaved** pattern instead of batch creation.
+
+### ❌ Wrong: Batch Creation
+
+```
+# Creates 5 files at once, then fills implementations
+1. Create file1.py, file2.py, file3.py, file4.py, file5.py (skeletons)
+2. Implement all functions
+3. Run guard → 40 missing_contract errors
+4. Retrofit contracts (descriptive, not prescriptive)
+```
+
+### ✅ Correct: Interleaved Pattern
+
+```
+TodoList:
+□ [SPECIFY] Write contracts for parser.py
+□ [BUILD] Implement parser.py
+□ [SPECIFY] Write contracts for validator.py
+□ [BUILD] Implement validator.py
+□ [SPECIFY] Write contracts for formatter.py
+□ [BUILD] Implement formatter.py
+```
+
+### Function-Level Gates
+
+For each file:
+
+```python
+# Step 1: Create file with contracts only (body = ...)
+@pre(lambda text: len(text) > 0)
+@post(lambda result: all(isinstance(t, Token) for t in result))
+def tokenize(text: str) -> list[Token]:
+    """Tokenize input text."""
+    ...
+
+@pre(lambda tokens: len(tokens) > 0)
+@post(lambda result: isinstance(result, AST))
+def parse(tokens: list[Token]) -> AST:
+    """Parse tokens into AST."""
+    ...
+```
+
+```bash
+# Step 2: Verify contract coverage
+$ invar guard -c src/core/parser.py
+Contract Coverage Check
+========================================
+Files: 1 | Functions: 2
+
+Coverage: 2/2 (100%) ✓
+Trivial:  0/2 (0%)   ✓
+
+Ready for BUILD phase.
+```
+
+```python
+# Step 3: Implement (only after coverage check passes)
+@pre(lambda text: len(text) > 0)
+@post(lambda result: all(isinstance(t, Token) for t in result))
+def tokenize(text: str) -> list[Token]:
+    """
+    Tokenize input text.
+
+    >>> tokenize("hello world")
+    [Token('hello'), Token('world')]
+    """
+    return [Token(word) for word in text.split()]
+```
+
+```bash
+# Step 4: Full verification
+$ invar guard --changed
+Guard passed.
+
+# Step 5: Proceed to next file
+```
+
+### Violation Self-Check
+
+Before writing ANY implementation code, ask:
+
+1. "Have I written the contract for THIS function?"
+2. "Have I shown it in my response?"
+3. "Have I run `invar guard -c`?"
+
+If any NO → Stop. Write contract first.
+
+### Benefits
+
+| Without DX-63 | With DX-63 |
+|---------------|------------|
+| 81 errors at end | 0 errors |
+| 4+ guard cycles | 1 cycle |
+| ~7000 tokens | ~4000 tokens |
+| Descriptive contracts | Prescriptive contracts |
+
 ## When to Use Visible Workflow
 
 Use for:

{invar_tools-1.5.0 → invar_tools-1.7.0}/CLAUDE.md

@@ -8,33 +8,36 @@
 | **Shell** | Returns `Result[T, E]` from `returns` library |
 | **Flow** | USBV: Understand → Specify → Build → Validate |
 
-<!--/invar:critical--><!--invar:managed version="5.0"-->
-# Project Development Guide
+### Contract Rules (CRITICAL)
 
-> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
+```python
+# ❌ WRONG: Lambda must include ALL parameters
+@pre(lambda x: x >= 0)
+def calc(x: int, y: int = 0): ...
 
-## Check-In (DX-54)
+# ✅ CORRECT: Include defaults too
+@pre(lambda x, y=0: x >= 0)
+def calc(x: int, y: int = 0): ...
 
-Your first message MUST display:
+# ❌ WRONG: @post cannot access parameters
+@post(lambda result: result > x)  # 'x' not available!
 
-```
-✓ Check-In: [project] | [branch] | [clean/dirty]
+# ✅ CORRECT: @post only sees 'result'
+@post(lambda result: result >= 0)
 ```
 
-Actions:
-1. Read `.invar/context.md` (Key Rules + Current State + Lessons Learned)
-2. Show one-line status
+<!--/invar:critical--><!--invar:managed version="5.0"-->
+# Project Development Guide
 
-Example:
-```
-✓ Check-In: MyProject | main | clean
-```
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
 
-**Do NOT execute guard or map at Check-In.**
-Guard is for VALIDATE phase and Final only.
+## Check-In
 
-This is your sign-in. The user sees it immediately.
-No visible check-in = Session not started.
+> 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.
 
 ---
 
@@ -70,6 +73,14 @@ src/{project}/
 | 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 |
@@ -80,6 +91,8 @@ src/{project}/
 | .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:
@@ -150,18 +163,26 @@ Guard triggers `review_suggested` for: security-sensitive files, escape hatches
 
 ## Workflow Routing (MANDATORY)
 
-When user message contains these triggers, you MUST invoke the corresponding skill:
+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.**
 
-| Trigger Words | Skill | Notes |
-|---------------|-------|-------|
-| "review", "review and fix" | `/review` | Adversarial review with fix loop |
-| "implement", "add", "fix", "update" | `/develop` | Unless in review context |
-| "why", "explain", "investigate" | `/investigate` | Research mode, no code changes |
-| "compare", "should we", "design" | `/propose` | Decision facilitation |
+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):**
-- "Am I in a workflow?"
-- "Did I invoke the correct skill?"
+- "Did I call `Skill(skill="...")`?"
+- "Am I following the SKILL.md instructions?"
 
 ---
 
@@ -241,7 +262,7 @@ pip install -e runtime/    # Runtime in dev mode
 <!-- ========================================================================
      USER REGION - EDITABLE
      Add your team conventions and project-specific rules below.
-     This section is preserved across invar update and sync-self.
+     This section is preserved across `invar update` and `invar dev sync`.
      ======================================================================== -->
 <!--/invar:user-->
 

{invar_tools-1.5.0 → invar_tools-1.7.0}/INVAR.md

@@ -267,6 +267,7 @@ invar guard              # Full: static + doctests + CrossHair + Hypothesis
 invar guard --static     # Static only (quick debug, ~0.5s)
 invar guard --changed    # Modified files only
 invar guard --coverage   # Collect branch coverage
+invar guard -c           # Contract coverage only (DX-63)
 invar sig <file>         # Show contracts + signatures
 invar map --top 10       # Most-referenced symbols
 invar rules              # List all rules with detection/hints (JSON)

{invar_tools-1.5.0 → invar_tools-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.5.0
+Version: 1.7.0
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme

{invar_tools-1.5.0 → invar_tools-1.7.0}/docs/proposals/DX-62-proactive-reference-reading.md

@@ -252,7 +252,7 @@ class PatternSuggestion:
 
 ### Phase 1: Context.md Task Router (Low Risk)
 - Add Task Router section to context.md template
-- Update existing projects via `invar sync-self`
+- Update existing projects via `invar dev sync`
 - No behavior change required, just improved guidance
 
 ### Phase 2: Pre-Flight Confirmation (Medium Risk)

invar_tools-1.7.0/docs/proposals/DX-64-version-display-unification.md

@@ -0,0 +1,104 @@
+# DX-64: 版本显示统一
+
+## 问题描述
+
+`invar version` 命令显示 `1.0.0`，但实际 PyPI 包版本是 `1.5.0`。
+
+### 当前行为
+
+```bash
+$ invar version
+invar 1.0.0
+
+$ pip show invar-tools | grep Version
+Version: 1.5.0
+```
+
+### 问题影响
+
+1. **用户困惑** - 不清楚实际安装的版本
+2. **故障排除困难** - 报告问题时版本信息不准确
+3. **升级验证困难** - 无法确认升级是否成功
+
+## 提案方案
+
+### 方案 A: 显示包版本 (推荐)
+
+从 `importlib.metadata` 获取实际包版本:
+
+```python
+import importlib.metadata
+
+@app.command()
+def version() -> None:
+    """Show Invar version."""
+    pkg_version = importlib.metadata.version("invar-tools")
+    console.print(f"invar-tools {pkg_version}")
+```
+
+**输出:**
+```
+invar-tools 1.5.0
+```
+
+### 方案 B: 同时显示包版本和协议版本
+
+```python
+@app.command()
+def version() -> None:
+    """Show Invar version."""
+    pkg_version = importlib.metadata.version("invar-tools")
+    protocol_version = "5.0"  # 从 INVAR.md 或配置读取
+    console.print(f"invar-tools {pkg_version}")
+    console.print(f"protocol {protocol_version}")
+```
+
+**输出:**
+```
+invar-tools 1.5.0
+protocol 5.0
+```
+
+### 方案 C: 详细版本信息
+
+```python
+@app.command()
+def version(verbose: bool = False) -> None:
+    """Show Invar version."""
+    pkg_version = importlib.metadata.version("invar-tools")
+
+    if verbose:
+        console.print(f"invar-tools: {pkg_version}")
+        console.print(f"protocol: 5.0")
+        console.print(f"python: {sys.version.split()[0]}")
+        console.print(f"platform: {sys.platform}")
+    else:
+        console.print(f"invar-tools {pkg_version}")
+```
+
+## 实现计划
+
+1. 修改 `src/invar/shell/commands/guard.py` 中的 `version` 命令
+2. 使用 `importlib.metadata.version()` 获取包版本
+3. 可选: 添加 `--verbose` 标志显示详细信息
+
+## 影响评估
+
+| 维度 | 影响 |
+|------|------|
+| 复杂度 | 低 |
+| 风险 | 低 |
+| 向后兼容 | 是 (输出格式变化) |
+| 测试 | 需更新版本测试 |
+
+## 决策
+
+**推荐方案 A** - 简单直接，解决核心问题。
+
+---
+
+*提案状态: ✅ 已完成*
+*创建日期: 2025-12-29*
+*完成日期: 2025-12-29*
+*来源: v1.5.0 测试报告 V150-01*
+*实现: commit c1a446e*

invar_tools-1.7.0/docs/proposals/DX-65-single-file-guard.md

@@ -0,0 +1,157 @@
+# DX-65: Guard 单文件支持
+
+## 问题描述
+
+`invar guard` 命令只接受目录路径，不支持单文件验证。
+
+### 当前行为
+
+```bash
+$ invar guard src/core/calculator.py
+Error: Invalid value for '[PATH]': Directory 'src/core/calculator.py' is a file.
+```
+
+### 用户场景
+
+1. **快速验证单个文件** - 修改一个文件后想快速检查
+2. **精确定位问题** - 已知问题在某文件，只想检查该文件
+3. **CI/CD 优化** - 只验证 PR 中变更的文件
+
+## 提案方案
+
+### 方案 A: 自动检测路径类型 (推荐)
+
+```python
+@app.command()
+def guard(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Project root directory or single file",
+        exists=True,
+    ),
+    ...
+) -> None:
+    if path.is_file():
+        # 单文件模式
+        files_to_check = [path]
+    else:
+        # 目录模式
+        files_to_check = find_python_files(path)
+```
+
+**用法:**
+```bash
+invar guard src/core/calculator.py  # 单文件
+invar guard src/core/               # 目录
+invar guard                         # 项目根目录
+```
+
+### 方案 B: 显式标志
+
+```python
+@app.command()
+def guard(
+    path: Path = ...,
+    file: bool = typer.Option(False, "--file", "-f", help="Treat path as file"),
+    ...
+) -> None:
+    if file:
+        files_to_check = [path]
+    else:
+        files_to_check = find_python_files(path)
+```
+
+**用法:**
+```bash
+invar guard -f src/core/calculator.py
+invar guard --file src/core/calculator.py
+```
+
+### 方案 C: 多路径支持
+
+```python
+@app.command()
+def guard(
+    paths: list[Path] = typer.Argument(
+        [Path(".")],
+        help="Files or directories to check",
+    ),
+    ...
+) -> None:
+    files_to_check = []
+    for path in paths:
+        if path.is_file():
+            files_to_check.append(path)
+        else:
+            files_to_check.extend(find_python_files(path))
+```
+
+**用法:**
+```bash
+invar guard src/core/calculator.py src/core/validator.py
+invar guard src/core/*.py  # Shell 展开
+```
+
+## 实现细节
+
+### 配置加载
+
+单文件模式仍需加载项目配置:
+
+```python
+def guard_single_file(file_path: Path) -> Result[GuardReport, str]:
+    # 向上查找 pyproject.toml 或 invar.toml
+    project_root = find_project_root(file_path)
+    config = load_config(project_root)
+
+    # 确定文件分类 (Core/Shell)
+    classification = classify_file(file_path, config)
+
+    # 运行相应规则
+    return run_rules(file_path, classification, config)
+```
+
+### 输出格式
+
+单文件模式可简化输出:
+
+```json
+{
+  "status": "passed",
+  "file": "src/core/calculator.py",
+  "classification": "core",
+  "errors": 0,
+  "warnings": 1,
+  "fixes": [...]
+}
+```
+
+## 与现有功能的交互
+
+| 功能 | 单文件支持 | 说明 |
+|------|------------|------|
+| `--changed` | 兼容 | 如果文件未变更，跳过 |
+| `-c` (contracts-only) | 兼容 | 只检查该文件合约 |
+| `--coverage` | 需调整 | 覆盖率只针对单文件 |
+| `--strict` | 兼容 | 应用于单文件 |
+
+## 影响评估
+
+| 维度 | 影响 |
+|------|------|
+| 复杂度 | 中 |
+| 风险 | 低 |
+| 向后兼容 | 是 |
+| 测试 | 需新增单文件测试 |
+
+## 决策
+
+**推荐方案 A** - 自动检测最符合用户直觉。
+
+---
+
+*提案状态: ✅ 已完成*
+*创建日期: 2025-12-29*
+*完成日期: 2025-12-29*
+*来源: v1.5.0 测试报告 V150-02*
+*实现: commit 6eeaf9e*