anima-cli 0.1.0__tar.gz

anima_cli-0.1.0/.agents/commands/audit.md

@@ -0,0 +1,146 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
+# Audit
+
+Read-only code review. Reports issues without fixing them.
+
+---
+
+## Behavior
+
+1. Analyze code for issues (style, bugs, security, architecture)
+2. Report findings with file:line references
+3. **Do NOT make any changes** - report only
+
+---
+
+## Adversarial Reviewer Persona
+
+You are an **adversarial code reviewer**. Your job is to FIND PROBLEMS.
+
+### Your Mindset
+
+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 NOT here to:
+- Validate that code works
+- Confirm the implementer did a good job
+- Be nice or diplomatic
+
+You ARE here to:
+- Find bugs, logic errors, edge cases
+- Challenge whether contracts have semantic value
+- Identify code smells and duplication
+- Question every escape hatch
+- Check if code matches contracts (not if code "seems right")
+
+**Your success is measured by problems found, not code approved.**
+
+---
+
+## Review Checklist
+
+> **Principle:** Only items requiring semantic judgment. Mechanical checks are excluded (see bottom).
+
+### 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. 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. 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?
+- [ ] What happens with unexpected inputs?
+
+### 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)
+
+---
+
+## Report Format
+
+For each issue found, use severity levels:
+
+| Severity | Meaning |
+|----------|---------|
+| **CRITICAL** | Must fix before completion |
+| **MAJOR** | Fix or provide written justification |
+| **MINOR** | Optional, can defer |
+
+```markdown
+### [CRITICAL/MAJOR/MINOR] Issue Title
+
+**Location:** file.py:line_number
+**Category:** contract_quality | logic_error | security | escape_hatch | code_smell
+**Problem:** What's wrong
+**Suggestion:** How to fix (but don't implement)
+```
+
+---
+
+## Instructions
+
+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.
+
+---
+
+Now review the recent changes or the files specified by the user.

anima_cli-0.1.0/.agents/commands/guard.md

@@ -0,0 +1,83 @@
+---
+_invar:
+  version: "5.0"
+  type: command
+---
+
+# 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.

anima_cli-0.1.0/.agents/instructions.md

@@ -0,0 +1,103 @@
+<!--invar:begin-->
+## Invar
+
+**CRITICAL: Write `@pre`/`@post` contracts and at least one doctest BEFORE implementing a Core function. Guard rejects uncontracted Core code.**
+
+### Architecture
+
+| Zone | Path | Rules |
+|------|------|-------|
+| Core | `**/core/**` | `@pre` + `@post` + doctest, no I/O imports |
+| Shell | `**/shell/**` | returns `Result[T, E]`, handles I/O |
+
+If code touches files, network, env vars, time, randomness, or subprocesses, use Shell.
+
+### Verification
+
+Run `invar guard` after changes. Fix errors before committing.
+
+### Tools
+
+| Tool | Use |
+|------|-----|
+| `invar guard` | verify architecture and contracts |
+| `invar sig <file>` | inspect signatures and contracts |
+| `invar map [path]` | inspect entry points |
+| `invar refs <file>::<symbol>` | inspect references |
+
+### Contract Traps
+
+```python
+# @pre must include all parameters, including defaults
+@pre(lambda x, y=0: x >= 0)
+def calc(x: int, y: int = 0): ...
+
+# @post only receives result
+@post(lambda result: result >= 0)
+```
+
+### Escape Hatches
+
+```python
+# @invar:allow dead_export: CLI entry point called by framework
+```
+
+Exact syntax and repair patterns: `INVAR.md`
+<!--invar:end-->
+
+---
+
+<!-- VECTL:AGENTS:BEGIN -->
+## Plan Tracking (vectl)
+
+vectl tracks this repo's implementation plan as a structured `plan.yaml`:
+what to do next, who claimed it, and what counts as done (with verification evidence).
+
+Full guide: `vectl_guide` (CLI fallback: `vectl guide`)
+Quick view: `vectl_status` (CLI fallback: `vectl status`)
+
+### MCP vs CLI
+- Source of truth: `plan.yaml` (channel-agnostic).
+- **Always prefer MCP tools** (`vectl_status`, `vectl_claim`, `vectl_complete`, etc.) when available.
+- CLI fallback priority: `uv run vectl` > `vectl` > `uvx vectl`.
+- Evidence requirements are identical across MCP and CLI.
+
+### Claim-time Guidance
+- `vectl claim` may emit a bounded Guidance block delimited by:
+  - `--- VECTL:GUIDANCE:BEGIN ---`
+  - `--- VECTL:GUIDANCE:END ---`
+- For automation/CI: use `vectl claim --no-guidance` to keep stdout clean.
+
+### plan.yaml — Managed File (DO NOT EDIT DIRECTLY)
+
+`plan.yaml` is exclusively owned by vectl. Direct edits (Edit, Write, sed, or
+any file tool) **will** corrupt plan state — vectl performs CAS writes, lock
+recalculation, and schema validation on every save, none of which run on direct
+edits.
+
+**To modify plan state, ONLY use:**
+- MCP (preferred): `vectl_claim`, `vectl_complete`, `vectl_mutate`, etc.
+- CLI (fallback): `uv run vectl claim`, `vectl claim`, or `uvx vectl claim`, etc.
+
+If a vectl command fails, report the error — do **not** edit `plan.yaml`
+directly as a workaround. Use `vectl guide stuck` for troubleshooting.
+
+### Rules
+- One claimed step at a time.
+- Evidence is mandatory when completing (commands run + outputs + gaps).
+- Spec uncertainty: leave `# SPEC QUESTION: ...` in code, do not guess.
+
+### Step ID Uniqueness
+**Step IDs must be globally unique across ALL phases.**
+- Example: `auth.login` and `api.login` are different step IDs.
+- Example: Using just `login` in two phases creates a duplicate — not allowed.
+- If you have legacy duplicate step IDs, use `vectl migrate-step-id --dry-run`
+  to preview and `--yes` to repair.
+
+### For Architects / Planners
+- **Design Mode**: Run `vectl_guide` (CLI fallback: `vectl guide --on planning`) to learn the Architect Protocol.
+- **Ambiguity = Failure**: Workers will hallucinate if steps are vague.
+- **Constraint Tools**:
+  - `--evidence-template`: Force workers to provide specific proof (e.g., "Paste logs here").
+  - `--refs`: Pin specific files (e.g., "src/auth.py") to the worker's context.
+<!-- VECTL:AGENTS:END -->

anima_cli-0.1.0/.agents/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "invar": {
+      "type": "stdio",
+      "command": "uv",
+      "args": ["run", "invar", "mcp"]
+    }
+  }
+}

anima_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

anima_cli-0.1.0/.github/workflows/waterline-gate.yml

@@ -0,0 +1,34 @@
+name: Waterline Gate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  guard-waterline:
+    name: Guard Waterline Non-Regression
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install project dependencies
+        run: uv sync --dev
+
+      - name: Run tests (including repro scripts)
+        run: uv run pytest tests/ -v --tb=short
+
+      - name: Enforce frozen waterline gate
+        run: uv run python scripts/waterline_guard_gate.py

anima_cli-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Test artifacts (hermetic)
+.hypothesis/
+.lattice/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Anima state (local dev)
+.anima/
+
+# Claude Code / MCP local config
+.claude/
+.mcp.json
+.opencode/
+CLAUDE.md
+.invar/
+.vectl/
+
+.serena/
+.gemini/
+
+GEMINI.md
+AGENTS.md
+model_context_windows.json
+
+.final_evidence.yaml
+.gate-worktree*
+.coverage.*
+.final_evidence.yaml
+coverage.xml
+
+plan-api-*
+plan-api-*
+plan.yaml.lock
+plan-dashboard.html
+
+.evidence_spec_compliance_v2_max_turns_grace.yaml

anima_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+- repo: local
+  hooks:
+  - id: invar-md-protected
+    name: INVAR.md Protection
+    entry: bash -c 'if git diff --cached --name-only | grep -q "^INVAR.md$"; then
+      echo "Warning - INVAR.md was modified directly. Use git commit --no-verify if
+      intentional."; exit 1; fi'
+    language: system
+    pass_filenames: false
+    stages:
+    - pre-commit
+  - id: invar-guard
+    name: Invar Guard
+    entry: bash
+    args:
+    - -c
+    - "RULE_FILES=\"rule_meta.py rules.py contracts.py purity.py pyproject.toml\"\n\
+      STAGED=$(git diff --cached --name-only)\nFULL=false\nfor f in $RULE_FILES; do\n\
+      \  if echo \"$STAGED\" | grep -qE \"(^|/)${f}$\"; then FULL=true; break; fi\n\
+      done\nif [ \"$FULL\" = true ]; then\n  echo \"\u26A0\uFE0F  Rule change detected\
+      \ - running FULL guard\"\n  .venv/bin/invar guard\nelse\n  .venv/bin/invar guard\
+      \ --changed\nfi\n"
+    language: system
+    pass_filenames: false
+    stages:
+    - pre-commit
+    types:
+    - python

anima_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+
+- **Persona Hot-Swap**: Planning for runtime persona switching capability. The `ctl_switch_persona` tool is planned to allow an agent to change its persona mid-session while preserving conversation history, turn counters, token accounting, and MCP server state. **Not yet implemented.**
+
+  **Planned behavior:**
+  - Persona would no longer be immutable for running daemon agents
+  - New control tool: `ctl_switch_persona(persona_ref)` (planned)
+  - Persona switch would be applied at the next turn boundary (cooperative, not immediate)
+  - Conversation history would be preserved across persona switches
+  - Only one pending persona switch would be allowed at a time
+
+  **Documentation:**
+  - See [docs/INTERFACES.md Section D.5](./docs/INTERFACES.md#d5-ctl_switch_personapersona_ref) for planned API reference
+  - See [docs/DESIGN.md Section 8](./docs/DESIGN.md#8-persona-runtime-switchability) for architecture planning
+
+## [0.1.0] - 2026-03-01
+
+### Added
+
+- Initial release of anima CLI agent runner
+- Agent lifecycle management: run, spawn, chat, daemon modes
+- MCP server interface for status, interaction, and interruption
+- Built-in control tools: `ctl_finish`, `ctl_fail`, `ctl_request_approval`, `ctl_suspend_until`, `ctl_spawn_subagent`
+- Budget enforcement with grace finalization
+- State persistence in `$ANIMA_STATE` (default `~/.anima/`)
+- Interactive `talk` command with SSE streaming support
+- PersonaSpec JSON schema for agent configuration
+- JobSpec JSON schema for job configuration
+
+[Unreleased]: https://github.com/yourorg/anima/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/yourorg/anima/releases/tag/v0.1.0

anima_cli-0.1.0/INVAR.md

@@ -0,0 +1,112 @@
+# Invar Protocol
+
+## Before Writing Code
+
+1. If you are writing a Core function, write `@pre`, `@post`, and at least one doctest BEFORE implementation.
+2. If you are unsure whether code belongs in Core or Shell, use Shell.
+3. Run `invar guard` after changes. Fix errors before committing.
+
+## Core vs Shell
+
+Use Shell if the code does any of these:
+- reads or writes files
+- makes network requests
+- reads environment variables
+- uses current time or randomness without injection
+- performs subprocess or system I/O
+
+Use Core for pure logic that only transforms already-available data.
+
+| Zone | Path | Rules |
+|------|------|-------|
+| Core | `**/core/**` | `@pre` + `@post` + doctest, no I/O imports |
+| Shell | `**/shell/**` | returns `Result[T, E]`, performs I/O |
+
+## Contract Syntax Traps
+
+### `@pre` lambda must include all function parameters
+
+```python
+# WRONG
+@pre(lambda x: x >= 0)
+def calc(x: int, y: int = 0): ...
+
+# CORRECT
+@pre(lambda x, y=0: x >= 0)
+def calc(x: int, y: int = 0): ...
+```
+
+### `@post` only receives `result`
+
+```python
+# WRONG
+@post(lambda result: result > x)
+
+# CORRECT
+@post(lambda result: result >= 0)
+```
+
+### Contracts must be semantic, not just type checks
+
+```python
+# WEAK
+@pre(lambda x: isinstance(x, int))
+
+# BETTER
+@pre(lambda x: x > 0)
+@pre(lambda start, end: start < end)
+```
+
+## Canonical Core Example
+
+```python
+from invar_runtime import pre, post
+
+@pre(lambda price, discount: price > 0 and 0 <= discount <= 1)
+@post(lambda result: result >= 0)
+def discounted_price(price: float, discount: float) -> float:
+    """
+    >>> discounted_price(100, 0.2)
+    80.0
+    """
+    return price * (1 - discount)
+```
+
+## Canonical Shell Example
+
+```python
+from pathlib import Path
+from returns.result import Result, Success, Failure
+
+def read_config(path: Path) -> Result[str, str]:
+    try:
+        return Success(path.read_text())
+    except OSError as exc:
+        return Failure(str(exc))
+```
+
+## Escape Hatches
+
+```python
+# @invar:allow dead_export: CLI entry point called by framework
+# @invar:allow shell_complexity: orchestration requires many steps
+```
+
+Use escape hatches rarely and always include a reason.
+
+## Minimal Configuration
+
+```toml
+[tool.invar.guard]
+core_paths = ["src/myapp/core"]
+shell_paths = ["src/myapp/shell"]
+```
+
+## Common Guard Repairs
+
+| Error | Fix |
+|------|-----|
+| `missing_contract` | add `@pre`, `@post`, and a doctest before implementation |
+| `param_mismatch` | include every function parameter in the `@pre` lambda |
+| `shell_result` | return `Result[T, E]` from Shell functions |
+| `forbidden_import` | move I/O out of Core or inject the value as a parameter |