invar-tools 1.3.0__tar.gz → 1.3.2__tar.gz

invar_tools-1.3.2/.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.2/.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.2/.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-->

invar_tools-1.3.0/src/invar/templates/skills/review/SKILL.md.jinja → invar_tools-1.3.2/.claude/skills/review/SKILL.md

@@ -1,19 +1,30 @@
-<!--invar:skill version="{{ version }}"-->
-<!-- ========================================================================
-     SKILL REGION - DO NOT EDIT
-     This section is managed by Invar and will be overwritten on update.
-     To add project-specific extensions, use the "extensions" region below.
-     ======================================================================== -->
 ---
 name: review
 description: Adversarial code review with fix loop. Use after development, when Guard reports review_suggested, or user explicitly requests review. Finds issues that automated verification misses. Supports isolated mode (sub-agent) and quick mode (same context).
+_invar:
+  version: "5.0"
+  managed: skill
 ---
+<!--invar:skill-->
 
 # Review Mode
 
 > **Purpose:** Find problems that Guard, doctests, and property tests missed.
 > **Mindset:** Adversarial. Your success is measured by problems found, not code approved.
 
+## Adversarial Reviewer Persona
+
+Assume:
+- The code has bugs until proven otherwise
+- The contracts may be meaningless ceremony
+- The implementer may have rationalized poor decisions
+- Escape hatches may be abused
+
+You ARE here to:
+- Find bugs, logic errors, edge cases
+- Challenge whether contracts have semantic value
+- Check if code matches contracts (not if code "seems right")
+
 ## Entry Actions
 
 ### Context Refresh (DX-54)
@@ -50,23 +61,61 @@ WARNING: review_suggested - Low contract coverage
 
 ## Review Checklist
 
+> **Principle:** Only items requiring semantic judgment. Mechanical checks are handled by Guard.
+
 ### A. Contract Semantic Value
 - [ ] 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))`
 - [ ] Could someone implement correctly from contracts alone?
+- [ ] Are boundary conditions explicit in contracts?
 
-### B. Logic Verification
-- [ ] Do contracts correctly capture intended behavior?
-- [ ] Are there paths bypassing contract checks?
-- [ ] Is there dead code or unreachable branches?
+### B. Doctest Coverage
+- [ ] Do doctests cover normal cases?
+- [ ] Do doctests cover boundary cases?
+- [ ] Do doctests cover error cases?
+- [ ] Are doctests testing behavior, not just syntax?
 
-### C. Escape Hatch Audit
+### C. Code Quality
+- [ ] Is duplicated code worth extracting?
+- [ ] Is naming consistent and clear?
+- [ ] Is complexity justified?
+
+### D. Escape Hatch Audit
 - [ ] Is each @invar:allow justification valid?
 - [ ] Could refactoring eliminate the need?
+- [ ] Is there a pattern suggesting systematic issues?
+
+### E. Logic Verification
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths that bypass contract checks?
+- [ ] Are there implicit assumptions not in contracts?
+- [ ] Is there dead code or unreachable branches?
 
-### D. Security (if applicable)
-- [ ] Input validation against injection, XSS?
-- [ ] No hardcoded secrets?
+### F. Security
+- [ ] Are inputs validated against security threats (injection, XSS)?
+- [ ] No hardcoded secrets (API keys, passwords, tokens)?
+- [ ] Are authentication/authorization checks correct?
+- [ ] Is sensitive data properly protected?
+
+### G. Error Handling & Observability
+- [ ] Are exceptions caught at appropriate level?
+- [ ] Are error messages clear without leaking sensitive info?
+- [ ] Are critical operations logged for debugging?
+- [ ] Is there graceful degradation on failure?
+
+## Excluded (Covered by Guard)
+
+These are checked by Guard or linters - don't duplicate:
+- Core/Shell separation → Guard (forbidden_import, impure_call)
+- Shell returns Result[T,E] → Guard (shell_result)
+- Missing contracts → Guard (missing_contract)
+- File/function size limits → Guard (file_size, function_size)
+- Entry point thickness → Guard (entry_point_too_thick)
+- Escape hatch count → Guard (review_suggested)
 
 ## Review-Fix Loop
 
@@ -110,7 +159,6 @@ Convergence check:
 - [ ] Needs more work: [issues]
 ```
 <!--/invar:skill-->
-
 <!--invar:extensions-->
 <!-- ========================================================================
      EXTENSIONS REGION - USER EDITABLE