invar-tools 1.2.0__tar.gz → 1.3.1__tar.gz

invar_tools-1.2.0/src/invar/templates/commands/review.md → invar_tools-1.3.1/.claude/commands/audit.md

@@ -1,73 +1,14 @@
-# Code Review (Reviewer Role)
+# Audit
 
-## Mode Detection (Required First Step)
-
-Before reviewing, determine the appropriate mode:
-
-### Check for `review_suggested`
-
-Look at your conversation history for recent `invar guard` output, or run:
-```bash
-invar guard --changed
-```
-
-Check if `review_suggested` warning is present:
-```
-WARNING: review_suggested - High escape hatch count: N @invar:allow markers
-WARNING: review_suggested - Security-sensitive path detected
-WARNING: review_suggested - Low contract coverage
-```
-
-### Select Mode
-
-| Condition | Mode | Why |
-|-----------|------|-----|
-| `review_suggested` present | **Isolated** | Eliminates confirmation bias |
-| No trigger | **Quick** | Faster, context preserved |
-| User requests `--isolated` | **Isolated** | Explicit override |
-| User requests `--quick` | **Quick** | Explicit override |
-
----
-
-## Isolated Mode
-
-**Use when:** `review_suggested` triggered, or user explicitly requests isolation.
-
-Spawn an independent reviewer with fresh context using Task tool:
-
-```
-I'll spawn an independent reviewer to eliminate confirmation bias...
-
-[Task tool call]
-prompt: |
-  You are an adversarial code reviewer. Your job is to FIND PROBLEMS.
-
-  Review these files: {files_to_review}
-
-  Read .claude/commands/review.md for the full checklist, then:
-  1. Check contract semantic value (not just syntax)
-  2. Audit all escape hatches (@invar:allow)
-  3. Look for logic errors and edge cases
-  4. Check security if applicable
-
-  Report issues as CRITICAL/MAJOR/MINOR with file:line locations.
-
-  Your success is measured by problems found, not code approved.
-
-subagent_type: "general-purpose"
-```
-
-After receiving the sub-agent's report, summarize findings for the user.
-
-**Key:** The sub-agent has NO conversation history. It only sees the code.
+Read-only code review. Reports issues without fixing them.
 
 ---
 
-## Quick Mode
-
-**Use when:** No `review_suggested` trigger, routine review needed.
+## Behavior
 
-Proceed with same-context review below.
+1. Analyze code for issues (style, bugs, security, architecture)
+2. Report findings with file:line references
+3. **Do NOT make any changes** - report only
 
 ---
 
@@ -149,7 +90,7 @@ You ARE here to:
 
 ---
 
-## Excluded (Covered by Tools)
+## Excluded (Covered by Guard)
 
 These are checked by Guard or linters - don't duplicate:
 - Core/Shell separation → Guard (forbidden_import, impure_call)
@@ -157,7 +98,6 @@ These are checked by Guard or linters - don't duplicate:
 - Missing contracts → Guard (missing_contract)
 - File/function size limits → Guard (file_size, function_size)
 - Entry point thickness → Guard (entry_point_too_thick)
-- Magic numbers → Linters (ruff)
 - Escape hatch count → Guard (review_suggested)
 
 ---
@@ -166,11 +106,11 @@ These are checked by Guard or linters - don't duplicate:
 
 For each issue found, use severity levels:
 
-| Severity | Meaning | Enforcement |
-|----------|---------|-------------|
-| **CRITICAL** | Must fix before completion | Blocking |
-| **MAJOR** | Fix or provide written justification | Strong |
-| **MINOR** | Optional, can defer | Advisory |
+| Severity | Meaning |
+|----------|---------|
+| **CRITICAL** | Must fix before completion |
+| **MAJOR** | Fix or provide written justification |
+| **MINOR** | Optional, can defer |
 
 ```markdown
 ### [CRITICAL/MAJOR/MINOR] Issue Title
@@ -178,22 +118,20 @@ For each issue found, use severity levels:
 **Location:** file.py:line_number
 **Category:** contract_quality | logic_error | security | escape_hatch | code_smell
 **Problem:** What's wrong
-**Suggestion:** How to fix (if applicable)
+**Suggestion:** How to fix (but don't implement)
 ```
 
 ---
 
-## Instructions Summary
+## Instructions
 
-1. **Mode Detection:** Check for `review_suggested` in guard output
-2. **If Isolated Mode:** Spawn Task sub-agent (fresh context)
-3. **If Quick Mode:** Proceed with same-context adversarial review
-4. Go through each checklist category
-5. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
-6. Report with structured format above
-7. Be thorough and adversarial
+1. Run `invar guard --changed` to see current state
+2. Go through each checklist category
+3. For each issue, determine severity (CRITICAL/MAJOR/MINOR)
+4. Report with structured format above
+5. Be thorough and adversarial
 
-**Remember:** You are READ-ONLY. Report issues, don't fix them directly.
+**Remember:** You are READ-ONLY. Report issues, don't fix them.
 
 ---
 

invar_tools-1.3.1/.claude/commands/guard.md

@@ -0,0 +1,77 @@
+# Guard
+
+Run Invar verification on the project and report results.
+
+---
+
+## Behavior
+
+Execute `invar_guard()` and report:
+- Pass/fail status
+- Error count with details
+- Warning count with details
+
+**Do NOT fix issues** - just report verification results.
+
+---
+
+## When to Use
+
+- Quick verification check
+- Before committing changes
+- After pulling changes
+- To see current project health
+
+---
+
+## Execution
+
+Run verification:
+
+```
+invar_guard(changed=true)
+```
+
+Or for full project verification:
+
+```
+invar_guard()
+```
+
+---
+
+## Report Format
+
+```
+## Guard Results
+
+**Status:** PASS / FAIL
+**Errors:** N
+**Warnings:** N
+
+### Errors (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| missing_contract | src/foo.py | 42 | Function 'bar' has no @pre/@post |
+
+### Warnings (if any)
+
+| Rule | File | Line | Message |
+|------|------|------|---------|
+| function_size | src/baz.py | 15 | Function exceeds 50 lines |
+```
+
+---
+
+## Next Steps
+
+After reporting results:
+- If PASS: No action needed
+- If FAIL: User decides whether to fix issues
+
+**Remember:** You are READ-ONLY. Report results, don't fix them.
+
+---
+
+Now run verification on the current project.

invar_tools-1.3.1/.claude/skills/develop/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: develop
+description: Implementation phase following USBV workflow. Use when task is clear and actionable - "add", "implement", "create", "fix", "update", "build", "write". Requires Check-In at start and Final at end.
+_invar:
+  version: "5.0"
+  managed: skill
+---
+<!--invar:skill-->
+
+# Development Mode
+
+> **Purpose:** Implement solution following USBV workflow with verification.
+
+## Entry Actions (REQUIRED)
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /develop — [trigger detected, e.g. "add", "fix", "implement"]
+   Task: [user's request summary]
+```
+
+### Simple Task Detection
+
+If task appears simple (4+ signals: single file, clear target, additive change, <50 lines):
+
+```
+📊 Simple task (1 file, ~N lines).
+   Auto-orchestrate: investigate → develop → validate?
+   [Y/N]
+```
+
+- Y → Execute full cycle without intermediate confirmations
+- N → Proceed with normal USBV checkpoints
+- No response → Default to step-by-step (safe)
+
+## USBV Workflow
+
+### 1. UNDERSTAND
+
+- **Intent:** What exactly needs to be done?
+- **Inspect:** Use `invar_sig` to see existing contracts
+- **Context:** Read relevant code, understand patterns
+- **Constraints:** What must NOT change?
+
+### 2. SPECIFY
+
+- **Contracts FIRST:** Write `@pre`/`@post` before implementation
+- **Doctests:** Add examples for expected behavior
+- **Design:** Decompose complex tasks into sub-functions
+
+```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
+```
+
+### 3. BUILD
+
+**For complex tasks:** Enter Plan Mode first, get user approval.
+
+**Implementation rules:**
+- Follow the contracts written in SPECIFY
+- Run `invar_guard(changed=true)` frequently
+- Commit after each logical unit
+
+**Commit format:**
+```bash
+git add . && git commit -m "feat: [description]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### 4. VALIDATE
+
+- Run `invar_guard()` (full verification)
+- All TodoWrite items complete
+- Integration works (if applicable)
+
+## Task Batching
+
+For multiple tasks:
+1. Create TodoWrite with all items upfront
+2. Execute sequentially (not parallel)
+3. After each task:
+   - Commit changes
+- Run `invar_guard(changed=true)`
+- Update TodoWrite
+4. **Limits:** Max 5 tasks OR 4 hours OR Guard failure
+
+## Failure Handling
+
+| Guard Result | Action |
+|--------------|--------|
+| Static fixable (missing contract) | Auto-fix, retry (max 2) |
+| Test failure | Report to user, ask for guidance |
+| Contract violation | Report, suggest `/investigate` |
+| Repeated failure | Stop, ask user |
+
+## Common Guard Errors
+
+Quick reference for resolving common Guard errors:
+
+| Error | Cause | Quick Fix |
+|-------|-------|-----------|
+| `forbidden_import: io` | I/O library in Core | Use `iter(s.splitlines())` not `io.StringIO` |
+| `forbidden_import: os` | os module in Core | Accept `Path` as parameter instead |
+| `forbidden_import: pathlib` | pathlib in Core | Accept `Path` or `str` as parameter |
+| `internal_import` | Import inside function | Move import to module top |
+| `missing_contract` | Core function without @pre/@post | Add contract before implementation |
+| `empty_contract` | Contract with no condition | Add meaningful condition |
+| `redundant_type_contract` | Contract only checks types | Add semantic constraints (bounds, relationships) |
+| `partial_contract` | Only some params validated | Validate all params or document why partial |
+| `file_size` | File > 500 lines | Extract functions to new module |
+| `shell_result` | Shell function missing Result | Return `Result[T, E]` from `returns` |
+
+**Tip:** For `missing_contract`, Guard automatically suggests contracts based on parameter types.
+Check the "Suggested:" line in Guard output.
+
+**Note:** Use `from deal import pre, post` for lambda-based contracts.
+`invar_runtime.pre/post` are for Contract objects like `NonEmpty`.
+
+## Timeout Handling
+
+| Threshold | Duration | Action |
+|-----------|----------|--------|
+| Warning | 3 hours (75%) | Soft warning with options |
+| Hard stop | 4 hours (max) | Save state, exit |
+
+**75% Warning:**
+```
+⏱ Time check: /develop has been running for 3 hours.
+   Remaining estimate: [based on TodoWrite progress]
+
+   Options:
+   A: Continue (1 hour max remaining)
+   B: Wrap up current task and exit
+   C: Checkpoint and pause for later
+
+   Choice? (auto-continue in 2 minutes if no response)
+```
+
+**Hard Stop:**
+```
+⏱ /develop reached 4-hour limit.
+
+   Completed: [N]/[M] tasks
+   Current task: [description] - [%] complete
+
+   Saving state for resume. Run '/develop --resume' to continue.
+```
+
+## Exit Actions (REQUIRED)
+
+### Final
+
+```python
+invar_guard()
+```
+
+
+**Display:**
+```
+✓ Final: guard [PASS/FAIL] | [errors] errors, [warnings] warnings
+```
+
+### Auto-Review (DX-41)
+
+If Guard outputs `review_suggested`:
+
+```
+⚠ review_suggested: [reason]
+
+📍 Routing: /review — review_suggested triggered
+   Task: Review [N files changed]
+```
+
+Proceed directly to /review skill. User can say "skip" to bypass.
+
+## Phase Visibility (DX-51)
+
+**USBV phases must be visually distinct.** On each phase transition, display a phase header:
+
+### Phase Header Format
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Compact Format (brief updates)
+
+```
+📍 VALIDATE — Running guard...
+```
+
+### Three-Layer Visibility
+
+| Layer | What | Tool |
+|-------|------|------|
+| Skill | `/develop` | Routing announcement |
+| Phase | `SPECIFY (2/4)` | Phase header (this section) |
+| Tasks | Concrete items | TodoWrite |
+
+**Phase headers are SEPARATE from TodoWrite.**
+- Phase = where you are in workflow (visible in output)
+- TodoWrite = what tasks need doing (visible in status panel)
+
+**BUILD is internal work** — show header but no detailed breakdown.
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+| See contracts | `invar_sig <file>` |
+| Find entry points | `invar_map --top 10` |
+| Verify code | `invar_guard` |
+| Edit symbol | Serena `replace_symbol_body` |
+| Add after symbol | Serena `insert_after_symbol` |
+| Rename symbol | Serena `rename_symbol` |
+
+## Example
+
+```
+User: "Add input validation to parse_source"
+
+Agent:
+📍 Routing: /develop — "add" trigger detected
+   Task: Add input validation to parse_source
+
+✓ Check-In: Invar | main | clean
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → UNDERSTAND (1/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Current: accepts any string
+- Need: reject whitespace-only strings
+- File: src/invar/core/parser.py
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → SPECIFY (2/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+@pre(lambda source, path: len(source.strip()) > 0)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → BUILD (3/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Implementation...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 /develop → VALIDATE (4/4)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ guard PASS | 0 errors, 1 warning
+
+✓ Final: guard PASS | 0 errors, 1 warning
+```
+<!--/invar:skill-->
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific validation steps
+     - Custom commit message formats
+     - Additional tool integrations
+     - Team-specific workflows
+     ======================================================================== -->
+<!--/invar:extensions-->

invar_tools-1.3.1/.claude/skills/investigate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: investigate
+description: Exploration and understanding phase. Use when task is vague, needs analysis, or requires understanding before action. Triggers on "why", "what is", "how does", "explain", "understand", "analyze", "investigate", "explore". NO CODE CHANGES in this phase.
+_invar:
+  version: "5.0"
+  managed: skill
+---
+<!--invar:skill-->
+
+# Investigation Mode
+
+> **Purpose:** Understand before acting. Gather information, analyze code, report findings.
+
+## Constraints
+
+**FORBIDDEN in this phase:**
+- Edit, Write (no code changes)
+- git commit (nothing to commit)
+- Creating new files
+
+**ALLOWED:**
+- Read, Glob, Grep (exploration)
+- invar_sig, invar_map (perception)
+- WebSearch, WebFetch (research)
+
+## Entry Actions
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /investigate — [reason, e.g. "task is vague", "trigger 'why'"]
+   Task: [user's request summary]
+```
+
+### Entry Steps
+
+1. Display routing announcement (above)
+2. Run `invar_map(top=10)` for codebase orientation
+3. Explore relevant code and documentation
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+| See function contracts | `invar_sig(target="<file>")` |
+| Find entry points | `invar_map(top=10)` |
+| Search code patterns | Grep with regex |
+| Explore codebase | Task(Explore) agent |
+
+## Exit Format
+
+```markdown
+### Investigation Complete
+
+**Topic:** [what was investigated]
+
+**Findings:**
+1. [Key finding 1]
+2. [Key finding 2]
+3. [Key finding 3]
+
+**Details:**
+[Detailed explanation with file:line references]
+
+**Recommendation:**
+- [ ] /propose — Design decision needed
+- [ ] /develop — Ready to implement [specific task]
+- [ ] More investigation — [what's still unclear]
+
+**Next step?**
+```
+<!--/invar:skill-->
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific investigation checklists
+     - Custom analysis tools or scripts
+     - Domain-specific research sources
+     - Team documentation references
+     ======================================================================== -->
+<!--/invar:extensions-->

invar_tools-1.3.1/.claude/skills/propose/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: propose
+description: Decision facilitation phase. Use when design decision is needed, multiple approaches are valid, or user asks "should we", "how should", "which", "compare", "design", "architect". Presents options with trade-offs for human choice.
+_invar:
+  version: "5.0"
+  managed: skill
+---
+<!--invar:skill-->
+
+# Proposal Mode
+
+> **Purpose:** Facilitate human decision-making with clear options and trade-offs.
+
+## Entry Actions
+
+### Context Refresh (DX-54)
+
+Before any workflow action:
+1. Read `.invar/context.md` (especially Key Rules section)
+2. Display routing announcement
+
+### Routing Announcement
+
+```
+📍 Routing: /propose — [trigger detected, e.g. "should we", "compare", "design"]
+   Task: [decision topic summary]
+```
+
+### Entry Steps
+
+1. Display routing announcement (above)
+2. Explore relevant context if needed
+
+## Output Formats
+
+### Quick Decision (2-4 options)
+
+```markdown
+### Decision: [Topic]
+
+| Option | Description | Pros | Cons |
+|--------|-------------|------|------|
+| A: [name] | [brief] | [pros] | [cons] |
+| B: [name] | [brief] | [pros] | [cons] |
+
+**Recommendation:** [A/B] because [concise reason]
+
+**Your choice?**
+```
+
+### Formal Proposal (complex decision)
+
+Create `docs/proposals/DX-XX-[topic].md`:
+
+```markdown
+# DX-XX: [Title]
+
+**Status:** Discussion
+**Created:** [date]
+
+## Problem Statement
+[What needs to be decided]
+
+## Options
+
+### Option A: [Name]
+- **Description:** [What this involves]
+- **Pros:** [Benefits]
+- **Cons:** [Drawbacks]
+- **Effort:** Low/Medium/High
+
+### Option B: [Name]
+...
+
+## Recommendation
+[Which option and why]
+
+## Open Questions
+[What needs clarification]
+```
+
+## Exit Conditions
+
+| User Response | Next Action |
+|---------------|-------------|
+| Chooses option | /develop to implement |
+| Needs more info | /investigate for analysis |
+| Approves proposal | Document created |
+<!--/invar:skill-->
+<!--invar:extensions-->
+<!-- ========================================================================
+     EXTENSIONS REGION - USER EDITABLE
+     Add project-specific extensions here. This section is preserved on update.
+
+     Examples of what to add:
+     - Project-specific proposal templates
+     - Decision criteria or checklists
+     - Stakeholder notification rules
+     - Architecture decision record (ADR) formats
+     ======================================================================== -->
+<!--/invar:extensions-->