violin/AGENTS.md

Strategic-Automation/violin — AI Developer Guidance

Workspace developer guidance for AI coding agents (Antigravity, Hermes, Codex, Cursor) developing or maintaining violin.

1. Stack & Setup

• Python: 3.11 (.python-version, pyproject.toml)
• Package Manager: uv (uv sync --dev)
• Venv: .venv via uv

2. Mandatory Verification Commands

Run before declaring completion:

uv run pytest                                # Full test suite (100% pass)
uv run ruff check .                          # Linter check
uv run ruff format --check .                 # Format check (fix: uv run ruff format .)
uv run python -m plugins.violin_guard.release # Release gate check

3. Code Conventions & Architecture

• Hermes Runtime Contract: Target-touching CLI commands MUST use plugins.violin_guard typed tools (violin_exec, violin_record_ptt, violin_review_batch, violin_record_hypothesis, violin_target, violin_status, violin_listener). Never invoke flat CLI scripts (python violin_guard.py).
• Fail-Closed Validation: State parsers (hypotheses.py, ptt.py, command.py, targets.py) validate inputs fail-closed before mutating state.
• Section Preservation: Rewriters (_rewrite_hypotheses, update_task) MUST preserve template sections (## Observations, ## Decoy Trail, ## Research Log, ## Resolved Theories, table columns). Never manually overwrite hypotheses.md with unstructured narrative text; keep canonical ### H-XXX: blocks and status fields intact.
• Evidence Path Isolation: Save all raw evidence, dumps, tokens, and PoC outputs strictly under $ENG_DIR/evidence/<phase>/. Never place evidence files inside $ENG_DIR/state/ (reserved for runtime state tracking).
• Typed Schemas: Use Pydantic v2 BaseModel models in plugins/violin_guard/schemas.py.
• Encoding: Explicit encoding="utf-8" required for all text file operations.

4. Git & Branching Strategy

• Branches: codex/<topic> or dev
• Flow: codex/<topic> ──► dev ──► PR to master (master protected by GH013).

5. Hard Boundaries

1. NEVER Bypass Target Execution Guards: No raw shell execution for target commands.
2. NEVER Swallow Exceptions or Patch Tests Superficialy: Fix root causes; never mask errors or alter assertions.
3. NEVER Hardcode Target IPs: Resolve via violin_target or scope.yaml.
4. NEVER Declare Success Without Empirical Verification: Always run uv run pytest and uv run ruff check ..