violin/AGENTS.md

Strategic-Automation/violin — AI Developer Guidance

Workspace-scoped developer guidance for AI coding agents (Antigravity, Hermes, Codex, Cursor, etc.) developing, testing, or maintaining the violin codebase.

Note: For deployed end-user Hermes pentest installations, runtime identity and engagement rules are packaged in SOUL.md, .hermes.md, and skills/pentest/SKILL.md. This file governs AI agent developer behavior within this repository workspace.

---

1. Stack & Environment Setup

• Python Version: 3.11 (pinned in .python-version and pyproject.toml to match Hermes runtime).
• Package Manager: uv (use uv sync --dev to sync development environment).
• Virtual Environment: .venv created and managed via uv.

---

2. Mandatory Verification Commands

Run these commands to verify any code changes before declaring completion:

# 1. Run full test suite (must pass 100%)
uv run pytest

# 2. Run linter check
uv run ruff check .

# 3. Check code formatting (fix with `uv run ruff format .`)
uv run ruff format --check .

# 4. Validate release gate
uv run python -m plugins.violin_guard.release

---

3. Code Conventions & Architecture

• Hermes Runtime Contract: All target-touching CLI command execution in Violin engagements MUST go through plugins.violin_guard typed Hermes tool calls (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) as a substitute for typed tool calls.
• Fail-Closed Validation: All state parsers (hypotheses.py, ptt.py, command.py, targets.py) must validate inputs fail-closed before mutating filesystem state.
• Section Preservation: File rewriters (_rewrite_hypotheses, update_task) must preserve structural template sections (## Observations, ## Decoy Trail, ## Research Log, ## Resolved Theories, table columns).
• Typed Schemas: Use Pydantic v2 BaseModel models in plugins/violin_guard/schemas.py for all tool parameter specifications.
• File Encoding: Always specify encoding="utf-8" explicitly for all text file read/write operations.

---

4. Git & Branching Strategy

• Feature/Docs Branches: Use codex/<topic> or dev.
• Merge Flow: codex/<topic> ──► dev ──► PR to master.
• Master Branch: master is protected by GitHub repository rules (GH013); production releases require a Pull Request.

---

5. Hard Boundaries (What AI Agents Must Never Do)

1. NEVER Bypass Target Execution Guards: Never run target-touching commands directly in raw shell without violin_exec or violin_exec_burst.
2. NEVER Swallow Exceptions or Patch Tests Superficialy: Fix underlying root causes; never mask errors, return dummy fallbacks, or comment out failing assertions.
3. NEVER Hardcode Target IPs: Resolve target hosts dynamically via violin_target or scope.yaml.
4. NEVER Declare Success Without Empirical Verification: Always run uv run pytest and uv run ruff check . to prove zero regressions before finishing work.