hardproof: Instructions file for Codex

Hardproof Agent Instructions

This file loads as project context when Hermes Agent starts in the Hardproof repository root. Read it before making any changes.

Project Identity

• Hardproof is a persistent, risk-aware engineering protocol for Hermes Agent.
• Current public release: v1.0.1 Proven (PyPI, GitHub).
• Current development boundary: none scheduled; the v0.4.0–v1.0.1 arc is released.
• Hardproof is a standalone Hermes plugin discovered through the hermes_agent.plugins entry-point group.
• It uses only public Hermes registration, hook, command, skill, and dispatch APIs.
• The plugin remains opt-in. Hardproof does not modify Hermes core files.

Read Order

Inspect these files in order before changing code:

1. AGENTS.md — this file
2. README.md — project overview and quick start
3. STATUS.md — current release and maintenance state
4. ROADMAP.md — roadmap and version plan
5. CONTRIBUTING.md — development workflow
6. docs/architecture.md — system architecture
7. docs/profiles.md — run profiles (Quick, Standard, Critical)
8. docs/security-model.md — security boundary
9. docs/configuration-and-migrations.md — config and migration guide
10. docs/policy-packs.md — language policy packs
11. Relevant ADRs in docs/adr/
12. Relevant tests in tests/

Do not assume the README is the entire specification.

Architecture Map

hardproof/
├── __init__.py              # Package version and public API
├── plugin.py                # Plugin registration entry point
├── compat.py                # Hermes API compatibility checks
├── config.py                # Configuration loading and defaults
├── constants.py             # Shared constants
├── errors.py                # Error types
├── paths.py                 # Project-local path resolution
├── commands/
│   ├── cli.py               # hermes hardproof CLI adapter
│   ├── slash.py             # /hardproof slash-command adapter
│   └── shared.py            # Shared command implementation
├── domain/
│   ├── enums.py             # RunStage, RunProfile, ApprovalGate, etc.
│   ├── models.py            # Run, VerificationCheck, SessionBinding, etc.
│   ├── snapshots.py         # Workspace state snapshots
│   ├── transitions.py       # Stage transition logic
│   └── workcells.py         # Workcell task/attempt state machines
├── hooks/
│   ├── context.py           # Pre-turn context injection
│   ├── sessions.py          # Session lifecycle hooks
│   ├── tool_policy.py       # Tool-call policy enforcement
│   └── verification.py      # Verification hook
├── isolation/
│   ├── guard.py             # Workspace isolation guard
│   └── adapters.py          # Execution backend adapters
├── kanban/
│   ├── worker.py            # Workcell implementer subagent contract
│   └── approvals.py         # Workcell approval routing
├── migrations/              # SQL migration files
├── policy/
│   ├── packs.py             # Language policy packs (Python, Node, Rust, Go)
│   ├── profiles.py          # Profile definitions
│   ├── stage_graph.py       # Stage graph configuration
│   ├── stage_rules.py       # Stage-aware rules
│   ├── terminal.py          # Terminal normalization
│   ├── tool_rules.py        # Tool-call rules
│   ├── trace.py             # Policy trace model
│   ├── verification_rules.py# Verification-specific rules
│   └── waivers.py           # Waiver logic
├── services/
│   ├── approvals.py         # Human approval service
│   ├── artifacts.py         # Run artifact service
│   ├── authority.py         # Human authority registry
│   ├── decisions.py         # Policy decision persistence
│   ├── evidence.py          # Verification evidence service
│   ├── fix_re_review.py     # Challenge Chamber fix/re-review loop
│   ├── hermes_children.py   # Public Hermes child-session adapter
│   ├── packages.py          # Package metadata services
│   ├── reports.py           # Report generation
│   ├── review_dispatch.py   # Challenge Chamber reviewer dispatch
│   ├── risks.py             # Risk classification
│   ├── runs.py              # Run management
│   ├── sessions.py          # Session binding
│   ├── tasks.py             # Task management
│   ├── waivers.py           # Waiver service
│   ├── workcell_artifacts.py# Workcell artifact handling
│   └── workcells.py         # Workcell scheduling and claims
├── skills/                  # 9 stage skill modules
│   ├── orchestrate/
│   ├── discover/
│   ├── design/
│   ├── plan/
│   ├── implement/
│   ├── review/
│   ├── verify/
│   ├── deliver/
│   └── learn/
├── storage/
│   ├── database.py          # SQLite database wrapper
│   ├── migrations.py        # Migration engine
│   └── repository.py        # Run repository
├── templates/               # Report templates
│   ├── completion.md
│   ├── design.md
│   ├── discovery.md
│   ├── plan.md
│   └── review.md
├── validation/              # Protocol SDK validation interfaces
├── vault/
│   └── lease.py             # Vault lease state
└── tools/
    ├── handlers.py          # Tool handler implementations
    └── schemas.py           # Exact JSON schemas for 6 tools