invar-tools 1.0.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar/templates/skills/develop/SKILL.md.jinja

@@ -0,0 +1,318 @@
+<!--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: 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.
+---
+
+# 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?
+{% 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
+
+- **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
+{% if syntax == "mcp" -%}
+- Run `invar_guard(changed=true)` frequently
+{% else -%}
+- Run `invar guard --changed` frequently
+{% endif -%}
+- 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
+
+{% if syntax == "mcp" -%}
+- Run `invar_guard()` (full verification)
+{% else -%}
+- Run `invar guard` (full verification)
+{% endif -%}
+- 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
+{% if syntax == "mcp" -%}
+   - Run `invar_guard(changed=true)`
+{% else -%}
+   - Run `invar guard --changed`
+{% endif -%}
+   - 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
+
+{% if syntax == "mcp" -%}
+```python
+invar_guard()
+```
+{% else -%}
+```bash
+invar guard
+```
+{% endif %}
+
+**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 |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See contracts | `invar_sig <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 -%}
+| 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/templates/skills/investigate/SKILL.md.jinja

@@ -0,0 +1,106 @@
+<!--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: 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.
+---
+
+# 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)
+{% if syntax == "mcp" -%}
+- invar_sig, invar_map (perception)
+{% else -%}
+- invar sig, invar map (perception)
+{% endif -%}
+- 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)
+{% if syntax == "mcp" -%}
+2. Run `invar_map(top=10)` for codebase orientation
+{% else -%}
+2. Run `invar map --top 10` for codebase orientation
+{% endif -%}
+3. Explore relevant code and documentation
+
+## Tool Selection
+
+| I want to... | Use |
+|--------------|-----|
+{% if syntax == "mcp" -%}
+| See function contracts | `invar_sig(target="<file>")` |
+| Find entry points | `invar_map(top=10)` |
+{% else -%}
+| See function contracts | `invar sig <file>` |
+| Find entry points | `invar map --top 10` |
+{% endif -%}
+| 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/templates/skills/propose/SKILL.md.jinja

@@ -0,0 +1,104 @@
+<!--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: 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.
+---
+
+# 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/templates/skills/review/SKILL.md.jinja

@@ -0,0 +1,125 @@
+<!--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).
+---
+
+# Review Mode
+
+> **Purpose:** Find problems that Guard, doctests, and property tests missed.
+> **Mindset:** Adversarial. Your success is measured by problems found, not code approved.
+
+## 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: /review — [trigger, e.g. "review_suggested", "user requested review"]
+   Task: [review scope summary]
+```
+
+## Mode Selection
+
+### Check Guard Output
+
+Look for `review_suggested` warning:
+```
+WARNING: review_suggested - High escape hatch count
+WARNING: review_suggested - Security-sensitive path detected
+WARNING: review_suggested - Low contract coverage
+```
+
+### Select Mode
+
+| Condition | Mode |
+|-----------|------|
+| `review_suggested` present | **Isolated** (spawn sub-agent) |
+| `--isolated` flag | **Isolated** |
+| Default (no trigger) | **Quick** (same context) |
+
+## Review Checklist
+
+### A. Contract Semantic Value
+- [ ] Does @pre constrain inputs beyond type checking?
+- [ ] Does @post verify meaningful output properties?
+- [ ] Could someone implement correctly from contracts alone?
+
+### B. Logic Verification
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths bypassing contract checks?
+- [ ] Is there dead code or unreachable branches?
+
+### C. Escape Hatch Audit
+- [ ] Is each @invar:allow justification valid?
+- [ ] Could refactoring eliminate the need?
+
+### D. Security (if applicable)
+- [ ] Input validation against injection, XSS?
+- [ ] No hardcoded secrets?
+
+## Review-Fix Loop
+
+```
+Round 1: Review → Find issues
+    ↓
+Fix CRITICAL + MAJOR (MINOR → backlog)
+    ↓
+Round 2: Re-review (if needed)
+    ↓
+Convergence check:
+- No CRITICAL/MAJOR → Exit ✓
+- No improvement → Exit (warn)
+- Round >= 3 → Exit (max)
+```
+
+## Severity Definitions
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| CRITICAL | Security, data loss, crash | SQL injection, unhandled null |
+| MAJOR | Logic error, missing validation | Wrong calculation, no bounds |
+| MINOR | Style, documentation | Naming, missing docstring |
+
+## Exit Report
+
+```markdown
+### Review Complete
+
+**Rounds:** [N]
+**Exit reason:** quality_met | max_rounds | no_improvement
+
+**Fixed:**
+- [list of fixed issues]
+
+**Remaining (MINOR - backlog):**
+- [list for later]
+
+**Recommendation:**
+- [ ] Ready for merge
+- [ ] Needs more work: [issues]
+```
+<!--/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 security review checklists
+     - Custom severity definitions
+     - Domain-specific code patterns to check
+     - Team code review standards
+     ======================================================================== -->
+<!--/invar:extensions-->