diff --git a/src/AGENTS.md b/src/AGENTS.md new file mode 100644 index 0000000..72ecad0 --- /dev/null +++ b/src/AGENTS.md @@ -0,0 +1,61 @@ +# AGENTS.md — P-PoR Repository + +## Overview +This project uses **three** automated LLM agents, executed by the +`openai-codex-ci` GitHub Action. All agents run with model **gpt-4o-mini**, +temperature **0.2**, and max_tokens **2048** unless overridden. + +| ID | Trigger | Role summary | +|-----|----------------------------|-----------------------------------------| +| BP | `tickets/BP-*.yaml` | Bulletproofs/Halo2 circuit generation | +| SN | `tickets/SN-*.yaml` | Snapshot & Merkle-tree code gen | +| CLI | `tickets/CLI-*.yaml` | Rust CLI glue, UX, docs | + +--- + +## 1. `BP` — Bulletproofs / Circuit Agent +- **Prompt template:** `prompts/bp_system.txt` +- **Capabilities:** Generates/edits Rust in `ppor_circuit`, adds unit tests. +- **Secrets:** _None_. Works only with public crates; never sees private keys. +- **Failure handling:** On `cargo test` failure, workflow auto-retries once; + if still failing, PR is labeled `codex-fail` for human triage. + +## 2. `SN` — Snapshot Agent +- **Prompt template:** `prompts/sn_system.txt` +- **Env vars exposed:** + - `BITCOIN_RPC_USER` & `BITCOIN_RPC_PASS` (masked in logs) +- **Allowed paths:** `snapshot_tool/**` +- **Forbidden:** Must not modify anything under `ppor_circuit/`. + +## 3. `CLI` — Front-End Agent +- **Prompt template:** `prompts/cli_system.txt` +- **Tasks:** Clap plumbing, progress bars, error messages, docs/README. +- **Special lints:** Must keep `#![forbid(unsafe_code)]` at crate root. + +--- + +## Prompt lifecycle +1. **Author** writes a YAML ticket → pushes to `tickets/`. +2. GitHub Action `codex-run.yaml` detects new file → picks agent via filename. +3. Action assembles: + - `agents/.system.txt` + - `tickets/.yaml` + - Code context snippets defined in ticket +4. Sends to OpenAI `/chat/completions`. +5. Creates PR `codex/` with generated diff + `codex-output.log`. +6. Human reviewer approves or requests changes. + +--- + +## Versioning & audit +- All prompt templates live in `agents/`, reviewed like source. +- Any change to an agent template **must** bump `version:` field in header + and include a changelog entry (`CHANGELOG.md` under “Prompt updates”). +- For security review, include this file + `agents/` directory in audit + bundle so cryptographers understand model exposure. + +--- + +## Future agents +If we add a **docs agent** or **refactor bot**, append a new section above and +update the table. Keep the ID short and unique. diff --git a/src/spec.md b/src/spec.md new file mode 100644 index 0000000..5a3c07c --- /dev/null +++ b/src/spec.md @@ -0,0 +1,126 @@ +Below is a **delta-update** to the spec that assumes your “development team” is mostly — or entirely — OpenAI Codex-powered automation, with you (and any auditors) providing human review and sign-off. + +--- + +## **P-PoR Spec v0.5 – Codex-First Delivery Model** + +> **Unchanged sections** (Purpose, Scope, Architecture, Security, Deliverables) still apply. +> Only the organisational & process parts are rewritten. + +| Section | Change | +| ------------------------ | ------------------------------------------------------------------ | +| **Stakeholders & Roles** | Collapse to three human roles + Codex engine | +| **Milestones** | Much shorter sprints; use “prompt cycles” not man-days | +| **Backlog Format** | YAML files that Codex ingests; each ticket = self-contained prompt | +| **Workflow** | GitHub Actions triggers Codex generations; humans review PRs | +| **Tooling** | Add `openai-codex-ci` runner; add `codemod` auto-refactor stage | + +--- + +### 1 Stakeholders & Responsibilities (Codex Model) + +| Role | Person / Agent | Duties | +| -------------------- | --------------------------- | ------------------------------------------- | +| **Product Owner** | **Adam Malin** | Business logic, acceptance tests, prompt QA | +| **Codex Dev Engine** | *OpenAI Codex 16-k context* | Generate / refactor Rust, Circuits, docs | +| **Security Auditor** | External firm | Final cryptographic review | +| **Release Steward** | *GitHub Action + GPG bot* | Deterministic build, tag, sign Artifacts | + +--- + +### 2 Automation-Centric Workflow + +```mermaid +flowchart TD + subgraph On PR creation + A[Create YAML ticket] -->|CI-trigger| B(Codex Action) + B --> C(PR with generated code/tests) + C --> D(Human Review / Approve) + D --> E(merge->main) + end + subgraph Nightly + F(Sched build) --> G(cargo test + audit) + end +``` + +#### 2.1 Ticket Format (`tickets/XYZ.yaml`) + +```yaml +id: BP-04 +description: | + Implement Bulletproofs wrapper that exposes + commit(v,r) and prove_sum_geq(min). +acceptance: + - cargo test --package ppor_circuit passes + - prove_sum_geq handles 64-bit values <= 21e14 +context_snippets: + - src/ppor_circuit/lib.rs:L1-120 + - docs/math/bulletproofs_overview.md +``` + +Codex Action reads the YAML, streams prompt → code, commits a new branch `codex/BP-04`, and opens a PR. + +#### 2.2 Human Review Checklist + +1. **Compiles & tests green** in CI. +2. Diff contains *no* unsafe Rust, `todo!()` or obvious side-channel. +3. Added/updated doc-comments OK. +4. Cargo-audit returns 0 vulnerabilities. + +--- + +### 3 Milestones (Prompt-Cycle View) + +| Cycle | Objective | Codex Tickets | Human SLA | +| -------------------------- | -------------------------------------- | ---------------------------------------- | ---------------- | +| **C1** (June 2 – 6) | Project skeleton, snapshot helper stub | `BP-00` init, `SN-00` snapshot, `CLI-00` | 48 h code review | +| **C2** (June 9 – 13) | Bulletproofs single-input PoC | `BP-01`, `TEST-01` fuzz | 48 h | +| **C3** (June 16 – 20) | Multi-input aggregation, progress bars | `BP-02`, `UX-01` | 48 h | +| **C4** (June 23 – 27) | Ownership Schnorr gadget | `OWN-01`, `TEST-02` | 72 h | +| **C5** (June 30 – July 4) | End-to-end demo, tag `v0.1.0` | `DEMO-01`, `DOC-01` | 72 h | + +*(Each “cycle” ≈ one week, assuming Codex can turn tickets within minutes to hours.)* + +--- + +### 4 CI/CD Add-Ons + +1. **`openai-codex-ci@v1` GitHub Action** + + * Inputs: `OPENAI_API_KEY`, ticket YAML path + * Outputs: PR branch with generated code & tests +2. **`codemod-lint` stage** + + * Runs `rustfmt`, `clippy --deny warnings`, automatic crate-feature pruning +3. **`semantic-pr-title` bot** – validates PR naming: `feat(bp): ...`, `fix(cli): ...` + +--- + +### 5 Updated Immediate TODOs + +| Ticket | Prompt Summary | ETA by Codex | Reviewer | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------- | +| `SN-00` | *“Write a Rust binary `snapshot_tool` that connects to a `bitcoind` RPC, iterates the UTXO set at a given height, emits a compact Merkle tree, and prints root hash.”* | < 1 h | Adam | +| `BP-00` | Scaffold `ppor_circuit` crate with feature-flag back-ends (`bulletproofs`, `halo2`), compile empty tests. | < 30 min | Adam | +| `CLI-00` | Generate Clap boilerplate (`generate`, `verify`) with progress bars. | < 30 min | Adam | + +*(Put these YAML files in `tickets/` and push; CI will spawn Codex PRs.)* + +--- + +### 6 Guidance for Writing Tickets / Prompts + +``` +DO: +• Provide exact crate versions & Cargo feature flags. +• Include code context snippets for Codex to patch. +• State *binary* acceptance commands (cargo test, cargo run). +DON’T: +• Leave high-level hand-wavy tasks (“make it faster”). +• Ask Codex to pick libraries — lock them first in ticket. +``` + +--- + +**Next step:** +Create the three seed tickets (`SN-00`, `BP-00`, `CLI-00`) and push to `main`. The Codex CI runner will open the first PR within minutes for your review.