violin: Instructions file for Codex

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 scripts/violin_guard.py check-release # Release gate check

3. Code Conventions & Architecture

• Hermes Runtime Contract: Target-touching commands MUST use the registered plugins.violin_guard tools (violin_exec, violin_record_ptt, violin_review_batch, violin_record_hypothesis, violin_target, violin_status). The standalone CLI is for administration and diagnostics, not target execution.
• Fail-Closed Validation: State parsers in plugins/violin_guard/core/ and command gates in plugins/violin_guard/gates/ 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/core/schemas.py.
• Encoding: Explicit encoding="utf-8" required for all text file operations.
• Library-First Development: Always use libraries—both Python standard library (e.g., functools.lru_cache, dataclasses, pathlib, contextlib, ipaddress, argparse, datetime.timedelta, shutil, re, shlex, hashlib) and declared external dependencies (pydantic, netaddr, yarl, filelock, pyyaml, bashlex, psutil)—instead of rolling custom code or manual parsing algorithms. Always check if existing built-in or project dependencies provide the required functionality before writing custom implementations.
• Spelling & Naming: Use American English throughout codebase symbols and exports (normalize_target, serialize, initialize). Avoid single-letter variable names (a, r) in public/internal handler signatures and function definitions.
• Timestamp Standardization: Use ISO-8601 UTC formats (datetime.now(UTC).isoformat()) across all state, receipt, and evidence timestamps.
• Process & Concurrency Safety: Never mutate global process environment (os.environ) in request handlers or adapter logic; pass parameters explicitly. Always acquire advisory locks (lock_file / workflow_lock) before writing to or appending to any state/feedback files.
• No Test Artifact Leakage in Production: Production code must NEVER inspect sys.modules for test-specific package names or test-specific shims. Use clean dependency injection, fixtures, or unittest.mock.
• Domain-Driven Test Naming: Name test files and test functions descriptively after the capability, invariant, or subsystem under test (e.g., test_batch_integrity.py), never after transient ticket numbers (task1, a1-a15) or static version numbers (roadmap_1_1_1).