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

invar/templates/CLAUDE.md.template

@@ -1,3 +1,16 @@
+<!--invar:critical-->
+## ⚡ Critical Rules
+
+| Always | Remember |
+|--------|----------|
+| **Verify** | `invar_guard` — NOT pytest, NOT crosshair |
+| **Core** | `@pre/@post` + doctests, NO I/O imports |
+| **Shell** | Returns `Result[T, E]` from `returns` library |
+| **Flow** | USBV: Understand → Specify → Build → Validate |
+
+<!--/invar:critical-->
+
+<!--invar:managed version="5.0"-->
 # Project Development Guide
 
 > **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion requirements.
@@ -120,16 +133,23 @@ When user message contains these triggers, you MUST invoke the corresponding ski
 - "Am I in a workflow?"
 - "Did I invoke the correct skill?"
 
----
+<!--/invar:managed-->
 
+<!--invar:project-->
 ## Project-Specific Rules
 
-<!-- Add your team conventions below -->
+<!-- Add your project structure and rules here -->
 
-## Overrides
+<!--/invar:project-->
 
-<!-- Document any exceptions to INVAR.md rules -->
+<!--invar:user-->
+<!-- ========================================================================
+     USER REGION - EDITABLE
+     Add your team conventions and project-specific rules below.
+     This section is preserved across invar update and sync-self.
+     ======================================================================== -->
+<!--/invar:user-->
 
 ---
 
-*Generated by `invar init`. Customize freely.*
+*Generated by `invar init` v5.0. Customize the user section freely.*

invar/templates/config/CLAUDE.md.jinja

@@ -1,3 +1,19 @@
+<!--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 |
+
+<!--/invar:critical-->
+
 <!--invar:managed version="{{ version }}"-->
 # Project Development Guide
 

invar/templates/config/context.md.jinja

@@ -55,17 +55,22 @@
 
 ## Documentation Structure
 
-| File | Owner | Edit? |
-|------|-------|-------|
-| INVAR.md | Invar | No — use `invar update` |
-| CLAUDE.md | User | Yes |
-| .invar/context.md | User | Yes (this file) |
-| .invar/examples/ | Invar | No |
+| File | Owner | Edit? | When to Read |
+|------|-------|-------|--------------|
+| INVAR.md | Invar | No — use `invar update` | Protocol details, Six Laws |
+| CLAUDE.md | User | Yes | Project rules |
+| .invar/context.md | User | Yes (this file) | Session start, refresh |
+| .invar/examples/ | Invar | No | Learning Core/Shell patterns |
 
 **Decision rule:** Is this Invar protocol or project-specific?
 - Protocol content → Already in INVAR.md, don't duplicate
 - Project-specific → Add to CLAUDE.md or here
 
+**When to consult INVAR.md:**
+- Unsure about Core/Shell separation rules
+- Need to understand Six Laws principles
+- Checking USBV workflow details
+
 ## Technical Debt
 
 {% if syntax == "mcp" -%}

invar/templates/context.md.template

@@ -2,11 +2,7 @@
 
 *Last updated: [DATE]*
 
-## Current State
-
-- Phase: [current development phase]
-- Working on: [current task or feature]
-- Blockers: None
+<!-- DX-58: Keep this file under 200 lines for efficient Check-In -->
 
 ## Key Rules (Quick Reference)
 
@@ -20,7 +16,7 @@
 1. Understand → 2. Specify (contracts first) → 3. Build → 4. Validate
 
 ### Verification
-- `invar guard` = static + doctests + CrossHair + Hypothesis
+- `invar_guard` = static + doctests + CrossHair + Hypothesis
 - Final must show: `✓ Final: guard PASS | ...`
 
 ## Self-Reminder
@@ -41,13 +37,39 @@
 
 ---
 
-## Recent Decisions
+## Current State
+
+- **Phase:** [current development phase]
+- **Working on:** [current task or feature]
+- **Blockers:** None
+
+## Active Work
+
+**Current focus:** [describe current focus]
 
-1. [Decision summary] - [Brief rationale]
+**Completed recently:**
+- [recent completion 1]
+- [recent completion 2]
+
+---
 
 ## Lessons Learned
 
-1. [Pitfall or issue] → [Solution or workaround]
+<!-- DX-58: Keep last 5-10 lessons here; older ones can be moved to .invar/archive/ if needed -->
+
+1. [Lesson] - [Brief explanation]
+
+---
+
+## Tool Priority
+
+| Task | Primary | Fallback |
+|------|---------|----------|
+| See contracts | `invar sig` | — |
+| Find entry points | `invar map --top` | — |
+| Verify | `invar guard` | — |
+
+---
 
 ## Documentation Structure
 
@@ -62,6 +84,8 @@
 - Protocol content → Already in INVAR.md, don't duplicate
 - Project-specific → Add to CLAUDE.md or here
 
+---
+
 ## Technical Debt
 
 *Run `invar guard` to check current status.*
@@ -70,15 +94,8 @@
 |------|---------|----------|
 | (none) | — | — |
 
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| INVAR.md | Protocol reference (Invar-managed) |
-| CLAUDE.md | Project guide (customize freely) |
-| src/core/ | Pure business logic |
-| src/shell/ | I/O adapters |
-
 ---
 
+<!-- ARCHIVE: For full session history, create .invar/archive/ directory -->
+
 *Update this file when: completing major tasks, making design decisions, discovering pitfalls.*

invar/templates/hooks/PostToolUse.sh.jinja

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Invar PostToolUse Hook
+# Protocol: v{{ protocol_version }} | Generated: {{ generated_date }}
+# DX-57: Git-based change detection with fallback
+
+TOOL_NAME="$1"
+
+# Check if hooks are disabled
+[[ -f ".claude/hooks/.invar_disabled" ]] && exit 0
+
+# Use session-specific state directory
+STATE_DIR="${CLAUDE_STATE_DIR:-/tmp/invar_hooks_$(id -u)}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+CHANGES_FILE="$STATE_DIR/changes"
+LAST_GUARD="$STATE_DIR/last_guard"
+LAST_CHECK_MARKER="$STATE_DIR/last_check"
+
+# ============================================
+# Reset state on guard run (MCP or CLI)
+# ============================================
+# MCP: invar_guard tool call
+if [[ "$TOOL_NAME" == "mcp__invar__invar_guard" ]]; then
+  date +%s > "$LAST_GUARD"
+  rm -f "$CHANGES_FILE"
+  touch "$LAST_CHECK_MARKER"
+  exit 0
+fi
+
+# CLI: Bash command containing "invar guard"
+if [[ "$TOOL_NAME" == "Bash" ]]; then
+  TOOL_INPUT="$2"
+  if echo "$TOOL_INPUT" | grep -qE '"command"[^}]*invar\s+guard'; then
+    date +%s > "$LAST_GUARD"
+    rm -f "$CHANGES_FILE"
+    touch "$LAST_CHECK_MARKER"
+    exit 0
+  fi
+fi
+
+# ============================================
+# Detect changes (git with fallback)
+# ============================================
+is_git_repo() {
+  git rev-parse --git-dir >/dev/null 2>&1
+}
+
+detect_changes() {
+  if is_git_repo; then
+    # Primary: Git-based detection (includes staged + unstaged)
+    { git diff --name-only -- '*.py' 2>/dev/null; git diff --cached --name-only -- '*.py' 2>/dev/null; } | sort -u
+  elif [[ -f "$LAST_CHECK_MARKER" ]]; then
+    # Fallback: Timestamp-based detection (approximate)
+    find . -name "*.py" -newer "$LAST_CHECK_MARKER" -type f 2>/dev/null | \
+      grep -v __pycache__ | grep -v '.venv' | head -20
+  fi
+  # Update marker for next check
+  touch "$LAST_CHECK_MARKER" 2>/dev/null
+}
+
+# Track changes
+CHANGED=$(detect_changes)
+if [[ -n "$CHANGED" ]]; then
+  echo "$CHANGED" >> "$CHANGES_FILE"
+  sort -u "$CHANGES_FILE" -o "$CHANGES_FILE" 2>/dev/null
+fi
+
+# ============================================
+# Smart trigger evaluation
+# ============================================
+CHANGE_COUNT=$(wc -l < "$CHANGES_FILE" 2>/dev/null | tr -d ' ' || echo 0)
+LAST_TIME=$(cat "$LAST_GUARD" 2>/dev/null || echo 0)
+NOW=$(date +%s)
+ELAPSED=$((NOW - LAST_TIME))
+
+SHOULD_REMIND=false
+REASON=""
+
+# Trigger 1: Accumulated changes (3+ files)
+if [[ $CHANGE_COUNT -ge 3 ]]; then
+  SHOULD_REMIND=true
+  REASON="$CHANGE_COUNT files changed"
+fi
+
+# Trigger 2: Core file changed (high priority)
+if grep -qE "/core/|/contracts/" "$CHANGES_FILE" 2>/dev/null; then
+  SHOULD_REMIND=true
+  REASON="core/ files modified"
+fi
+
+# Trigger 3: Time threshold (>5 min with changes)
+if [[ $ELAPSED -gt 300 && $CHANGE_COUNT -gt 0 ]]; then
+  SHOULD_REMIND=true
+  REASON=">5 min since last guard"
+fi
+
+# Output reminder if triggered
+if [[ "$SHOULD_REMIND" == "true" ]]; then
+  echo ""
+  echo "⚠️ Verification suggested: $REASON"
+  echo "   Run: {{ guard_cmd }} --changed"
+fi

invar/templates/hooks/PreToolUse.sh.jinja

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Invar PreToolUse Hook
+# Protocol: v{{ protocol_version }} | Generated: {{ generated_date }}
+# DX-57: Smart blocking with auto-escape for pytest/crosshair
+
+TOOL_NAME="$1"
+TOOL_INPUT="$2"
+
+# Check if hooks are disabled
+[[ -f ".claude/hooks/.invar_disabled" ]] && exit 0
+
+# Only process Bash commands
+[[ "$TOOL_NAME" != "Bash" ]] && exit 0
+
+# Parse command from JSON input
+# Primary: jq (accurate), Fallback: grep/sed (basic)
+if command -v jq &>/dev/null; then
+  CMD=$(echo "$TOOL_INPUT" | jq -r '.command // empty' 2>/dev/null)
+else
+  # Fallback: Extract command field using grep/sed (handles simple cases)
+  CMD=$(echo "$TOOL_INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*: *"\(.*\)"/\1/')
+fi
+[[ -z "$CMD" ]] && exit 0
+
+# ============================================
+# pytest blocking with smart escape
+# ============================================
+if echo "$CMD" | grep -qE '\bpytest\b|python.*-m\s+pytest\b'; then
+
+  # Auto-escape 1: Debugging mode (--pdb, --debug, --tb=long)
+  if echo "$CMD" | grep -qE '\-\-pdb|\-\-debug|\-\-tb='; then
+    echo "⚠️ pytest debugging allowed. Run {{ guard_cmd }} after."
+    exit 0
+  fi
+
+  # Auto-escape 2: External/vendor tests
+  if echo "$CMD" | grep -qE 'vendor/|third_party/|external/|node_modules/'; then
+    exit 0
+  fi
+
+  # Auto-escape 3: Explicit coverage collection
+  if echo "$CMD" | grep -qE '\-\-cov'; then
+    echo "⚠️ pytest coverage allowed. Run {{ guard_cmd }} for contract verification."
+    exit 0
+  fi
+
+  # Auto-escape 4: Environment variable override
+  if [[ "$INVAR_ALLOW_PYTEST" == "1" ]]; then
+    exit 0
+  fi
+
+  # Default: Block with helpful message
+  echo "❌ Use {{ guard_cmd }} instead of pytest"
+  echo "   {{ guard_cmd }} = static + doctests + CrossHair + Hypothesis"
+  echo ""
+  echo "   Auto-allowed: pytest --pdb (debug), pytest --cov (coverage)"
+  echo "   Manual escape: INVAR_ALLOW_PYTEST=1 pytest ..."
+  exit 1
+fi
+
+# ============================================
+# crosshair blocking (always redirect)
+# ============================================
+if echo "$CMD" | grep -qE '\bcrosshair\b'; then
+  if [[ "$INVAR_ALLOW_CROSSHAIR" == "1" ]]; then
+    exit 0
+  fi
+
+  echo "❌ Use {{ guard_cmd }} (includes CrossHair by default)"
+  echo "   Manual escape: INVAR_ALLOW_CROSSHAIR=1 crosshair ..."
+  exit 1
+fi
+
+exit 0

invar/templates/hooks/Stop.sh.jinja

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Invar Stop Hook
+# Protocol: v{{ protocol_version }} | Generated: {{ generated_date }}
+# DX-57: Session cleanup and unverified changes warning
+
+# Use session-specific state
+STATE_DIR="${CLAUDE_STATE_DIR:-/tmp/invar_hooks_$(id -u)}"
+CHANGES_FILE="$STATE_DIR/changes"
+
+# Check for unverified changes
+if [[ -f "$CHANGES_FILE" ]]; then
+  CHANGE_COUNT=$(wc -l < "$CHANGES_FILE" 2>/dev/null | tr -d ' ' || echo 0)
+  if [[ $CHANGE_COUNT -gt 0 ]]; then
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "⚠️  Invar: $CHANGE_COUNT Python files not verified"
+    echo "   Run before commit: {{ guard_cmd }} --changed"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  fi
+fi
+
+# Cleanup session state
+rm -rf "$STATE_DIR" 2>/dev/null

invar/templates/hooks/UserPromptSubmit.sh.jinja

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Invar UserPromptSubmit Hook
+# Protocol: v{{ protocol_version }} | Generated: {{ generated_date }}
+# DX-57: Protocol refresh with full INVAR.md injection
+
+USER_MESSAGE="$1"
+
+# Check if hooks are disabled
+[[ -f ".claude/hooks/.invar_disabled" ]] && exit 0
+
+# Use session-specific state
+STATE_DIR="${CLAUDE_STATE_DIR:-/tmp/invar_hooks_$(id -u)}"
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+# Session detection: Reset if state is stale (>4 hours)
+SESSION_MARKER="$STATE_DIR/session_start"
+MAX_AGE_SECONDS=14400  # 4 hours
+
+reset_session() {
+  rm -f "$STATE_DIR/msg_count" "$STATE_DIR/changes" 2>/dev/null
+  date +%s > "$SESSION_MARKER"
+}
+
+if [[ -f "$SESSION_MARKER" ]]; then
+  MARKER_TIME=$(cat "$SESSION_MARKER" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  AGE=$((NOW - MARKER_TIME))
+  if [[ $AGE -gt $MAX_AGE_SECONDS ]]; then
+    reset_session
+  fi
+else
+  reset_session
+fi
+
+COUNT_FILE="$STATE_DIR/msg_count"
+COUNT=$(cat "$COUNT_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNT_FILE"
+
+# ============================================
+# Keyword triggers (independent of count)
+# ============================================
+
+# pytest intent → immediate correction
+if echo "$USER_MESSAGE" | grep -qiE "run.*pytest|pytest.*test|用.*pytest"; then
+  echo "<system-reminder>Use {{ guard_cmd }}, not pytest.</system-reminder>"
+fi
+
+# Implementation intent → workflow reminder (after warmup)
+if [[ $COUNT -gt 3 ]]; then
+  if echo "$USER_MESSAGE" | grep -qiE "^implement|^fix|^add|^实现|^修复|^添加"; then
+    echo "<system-reminder>USBV: Specify contracts → Build → Validate</system-reminder>"
+  fi
+fi
+
+# ============================================
+# Progressive refresh based on message count
+# ============================================
+
+# Message 15: Lightweight checkpoint
+if [[ $COUNT -eq 15 ]]; then
+  echo "<system-reminder>"
+  echo "Checkpoint: guard=verify, sig=contracts, USBV workflow."
+  echo "</system-reminder>"
+fi
+
+# Message 25+: Full INVAR.md injection every 10 messages
+# SSOT: Inject entire protocol to ensure no content drift
+if [[ $COUNT -ge 25 && $((COUNT % 10)) -eq 0 ]]; then
+  echo "<system-reminder>"
+  echo "=== Protocol Refresh (message $COUNT) ==="
+  echo ""
+  cat << 'INVAR_EOF'
+{{ invar_protocol }}
+INVAR_EOF
+  echo "</system-reminder>"
+fi

invar/templates/hooks/__init__.py

@@ -0,0 +1 @@
+# Invar Claude Code hook templates (DX-57)

invar/templates/manifest.toml

@@ -103,8 +103,8 @@ overwrite = ["INVAR.md", ".invar/examples/"]
 merge = ["CLAUDE.md", ".claude/skills/"]
 skip = [".invar/context.md"]
 
-[commands.sync_self]
-# For Invar project only
+[commands.dev_sync]
+# For Invar project only (invar dev sync)
 syntax = "mcp"
 inject_project_additions = true
 

invar/templates/protocol/INVAR.md

@@ -36,6 +36,31 @@
 
 **Forbidden in Core:** `os`, `sys`, `subprocess`, `pathlib`, `open`, `requests`, `datetime.now`
 
+### Decision Tree: Core vs Shell
+
+```
+Does this function...
+│
+├─ Read or write files? ──────────────────→ Shell
+├─ Make network requests? ─────────────────→ Shell
+├─ Access current time (datetime.now)? ────→ Shell OR inject as parameter
+├─ Generate random values? ────────────────→ Shell OR inject as parameter
+├─ Print to console? ──────────────────────→ Shell (return data, Shell logs)
+├─ Access environment variables? ──────────→ Shell
+│
+└─ None of the above? ─────────────────────→ Core
+```
+
+**Pattern:** Inject impure values as parameters:
+```python
+# Core: receives 'now' as parameter (pure)
+def is_expired(expiry: datetime, now: datetime) -> bool:
+    return now > expiry
+
+# Shell calls with actual time
+expired = is_expired(token.expiry, datetime.now())
+```
+
 ## Core Example (Pure Logic)
 
 ```python
@@ -76,6 +101,50 @@ def read_config(path: Path) -> Result[dict, str]:
 
 More examples: `.invar/examples/`
 
+## Contract Rules
+
+### Lambda Signature (Critical)
+
+```python
+# WRONG: Lambda only takes first parameter
+@pre(lambda x: x >= 0)
+def calculate(x: int, y: int = 0): ...
+
+# CORRECT: Lambda must include ALL parameters (even defaults)
+@pre(lambda x, y=0: x >= 0)
+def calculate(x: int, y: int = 0): ...
+```
+
+Guard's `param_mismatch` rule catches this as ERROR.
+
+### Meaningful Contracts
+
+```python
+# Redundant - type hints already check this
+@pre(lambda x: isinstance(x, int))
+def calc(x: int): ...
+
+# Meaningful - checks business logic
+@pre(lambda x: x > 0)
+def calc(x: int): ...
+
+# Meaningful - checks relationship between params
+@pre(lambda start, end: start < end)
+def process_range(start: int, end: int): ...
+```
+
+### @post Scope
+
+```python
+# WRONG: @post cannot access function parameters
+@post(lambda result: result > x)  # 'x' not available!
+def calc(x: int) -> int: ...
+
+# CORRECT: @post can only use 'result'
+@post(lambda result: result >= 0)
+def calc(x: int) -> int: ...
+```
+
 ## Check-In (Required)
 
 Your first message MUST display:
@@ -184,27 +253,57 @@ When rule violation has valid architectural justification:
 def flask_handler(): ...
 ```
 
-See `invar rules` for all rule names.
+**Valid rule names for @invar:allow:**
+- `shell_result` — Shell function without Result return type
+- `entry_point_too_thick` — Entry point exceeds 15 lines
+- `forbidden_import` — I/O import in Core (rare, justify carefully)
+
+Run `invar rules` for complete rule catalog with hints.
 
 ## Commands
 
 ```bash
-invar guard              # Full: static + doctests + CrossHair + Hypothesis (default)
+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 sig <file>         # Show contracts + signatures
 invar map --top 10       # Most-referenced symbols
+invar rules              # List all rules with detection/hints (JSON)
 ```
 
 ## Configuration
 
 ```toml
+# pyproject.toml or invar.toml
 [tool.invar.guard]
-core_paths = ["src/myapp/core"]
-shell_paths = ["src/myapp/shell"]
-# DX-22: Doctest lines are always excluded from size calculations by default
+core_paths = ["src/myapp/core"]    # Default: ["src/core", "core"]
+shell_paths = ["src/myapp/shell"]  # Default: ["src/shell", "shell"]
+max_file_lines = 500               # Default: 500 (warning at 80%)
+max_function_lines = 50            # Default: 50
+# Doctest lines are excluded from size calculations
 ```
 
+## Troubleshooting
+
+### Size Limits (Agent Quick Reference)
+
+| Rule | Limit | Fix |
+|------|-------|-----|
+| `function_too_long` | **50 lines** | Extract helper: `_impl()` + main with docstring |
+| `file_too_long` | **500 lines** | Split by responsibility |
+| `entry_point_too_thick` | **15 lines** | Delegate to Shell functions |
+
+*Doctest lines excluded from counts. Limits configurable in `pyproject.toml`.*
+
+### Common Errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `param_mismatch` error | Lambda missing params | Include ALL params (even defaults) |
+| `shell_result` error | Shell func no Result | Add Result[T,E] or @invar:allow |
+| `is_failure()` not found | Wrong Result check | Use `isinstance(result, Failure)` |
+
 ---
 
-*Protocol v5.0 — USBV workflow (DX-32) | [Guide](docs/guide.md) | [Examples](.invar/examples/)*
+*Protocol v5.0 — USBV workflow (DX-32) | [Examples](.invar/examples/)*

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

@@ -1,13 +1,11 @@
-<!--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.
+_invar:
+  version: "{{ version }}"
+  managed: skill
 ---
+<!--invar:skill-->
 
 # Development Mode
 
@@ -303,7 +301,6 @@ Agent:
 ✓ Final: guard PASS | 0 errors, 1 warning
 ```
 <!--/invar:skill-->
-
 <!--invar:extensions-->
 <!-- ========================================================================
      EXTENSIONS REGION - USER EDITABLE

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

@@ -1,13 +1,11 @@
-<!--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.
+_invar:
+  version: "{{ version }}"
+  managed: skill
 ---
+<!--invar:skill-->
 
 # Investigation Mode
 
@@ -91,7 +89,6 @@ Before any workflow action:
 **Next step?**
 ```
 <!--/invar:skill-->
-
 <!--invar:extensions-->
 <!-- ========================================================================
      EXTENSIONS REGION - USER EDITABLE