Agents setup

.agent/AGENTS.md

@@ -1,142 +1,119 @@
 # OneShot Agent Policy
 
-This file defines mandatory behavior for every coding, documentation,
-infrastructure, data, and model agent working in this repository.
+This policy applies to code, documentation, infrastructure, data, and agent
+work in this repository.
 
 ## Instruction order
 
 1. Follow system and user instructions.
-2. Follow the root `AGENTS.md` and this file.
-3. Follow `.agent/MILESTONE_IMPLEMENTATION_LOOP.md` for milestone work.
-4. Follow the narrowest applicable repository documentation and configuration.
+2. Follow root `AGENTS.md` and this policy.
+3. Follow the task-specific documents and repo skills routed by root
+   `AGENTS.md`.
+4. Follow the narrowest applicable repository configuration.
 
-If instructions conflict, stop and surface the conflict. Do not silently choose
-the most convenient interpretation.
+Surface conflicts. Never silently weaken an invariant, review gate, or security
+boundary.
 
 ## Tool neutrality
 
-- Shared policy must remain independent of agent vendor, model, operating
-  system, and editor.
-- Codex, Claude, Antigravity, Cursor, or another capable agent may implement or
-  review a change.
-- Tool-specific repository files must be thin adapters pointing to the
-  canonical `AGENTS.md` and `.agent/` documents. Do not copy policy into them.
-- Personal prompts, permissions, model choices, and machine-specific commands
-  belong in ignored local files.
-- A gate reviewer must use a fresh read-only session, must not be the
-  implementation agent, and must identify its tool and platform-reported model
-  in the verdict. Record `not exposed by platform` when no model identifier is
-  available.
-- Different tools may perform Gate A and Gate B. Both must use the canonical
-  prompts and required verdict format.
-
-## Before making changes
-
-- Read the task, acceptance criteria, relevant code, and related documentation.
-- Inspect `git status`, the current branch, and the diff before editing.
-- Preserve unrelated user changes and never include them in a commit.
-- Identify the milestone, the smallest reviewable outcome, and explicit non-goals.
-- State assumptions that can materially affect behavior, security, privacy,
-  cost, licensing, or architecture.
-- Prefer evidence from the repository and official primary documentation over
-  memory for version-sensitive technical decisions.
-
-## Scope and architecture
-
-- One branch and pull request must represent one milestone or one tightly
-  related correction.
-- Keep scope lean and focused. Do not introduce speculative features, unused
-  dependencies, or unnecessary abstractions unless the active milestone explicitly
-  requires them.
-- Preserve clean separation of concerns: presentation/interface, orchestration,
-  domain logic, and external service adapters.
-- Validate all untrusted input at boundaries.
-- Handle state transitions, loading, empty states, and errors predictably.
-
-## Implementation rules
-
-- Write strict, readable code adhering to established style conventions.
-- Do not weaken compiler, lint, or type-check configurations to make a change pass.
-- Prefer small, typed interfaces at subsystem boundaries.
-- Add or update tests for behavior changes and regression fixes.
+- Codex, Claude, Antigravity, Cursor, or another capable agent may implement
+  work, but all tools follow the same canonical repository policy.
+- Tool adapters remain short pointers to root `AGENTS.md`; personal prompts,
+  permissions, models, and machine-specific commands stay in ignored files.
+- Gate A and Gate B use separate fresh, read-only FreePi processes. Each verdict
+  records the reviewer tool, platform-reported model (or `not exposed by
+  platform`), and immutable Git identities required by
+  `.agent/IMPLEMENTATION_LOOP.md`.
+
+## Product boundary
+
+OneShot's core promise is: `One job. Many retries. One settlement.`
+
+- OneShot owns authoritative Business Intent, Attempt, and Settlement state and
+  prevents duplicate committed settlements.
+- Privy provides corporate wallet access and scoped authorization, policy, and
+  spending permissions.
+- Arc is the USDC settlement rail.
+- The Graph provides live indexed history and recovery context. It is never the
+  duplicate-payment lock or authority for creating another Settlement.
+
+Read `.agent/PROJECT_CONTEXT.md`, `.agent/SECURITY_INVARIANTS.md`, and
+`.agent/SPONSOR_REQUIREMENTS.md` before changing these boundaries.
+
+## Non-negotiable invariants
+
+- `1 business intent -> at most 1 committed settlement`.
+- Keep one stable `business_intent_id` across retries, restarts, parallel
+  attempts, workers, and agent instances.
+- Treat `UNKNOWN` settlement state as a reconciliation requirement. Never
+  blindly repay.
+- Make state durable and transitions atomic and concurrency-safe.
+- Represent money as integer atomic units or `bigint`, never JavaScript
+  floating point.
+- Graph absence or indexing delay is not proof that payment did not happen.
+- Normal execution must not bypass Privy policy or OneShot controls.
+- Use testnet only unless the user explicitly authorizes another network.
+- Never log, expose, persist, commit, or send secrets, private keys, seed
+  phrases, tokens, wallet credentials, or sensitive runtime configuration.
+
+## Before changing files
+
+- Inspect the current branch, status, task acceptance criteria, relevant code,
+  existing diff, and any merge/rebase state.
+- Preserve unrelated user work and keep it out of commits.
+- Record material assumptions and active context in `.agent/context/`.
+- Use current primary documentation for version-sensitive integrations.
+- Do not create or materially revise the product implementation `plan.md` until
+  required skills and integration research are ready.
+
+## Implementation quality
+
+- Keep one branch and PR focused on one milestone or tightly related change.
+- Preserve clear ownership among interface, orchestration, domain state, and
+  external adapters.
+- Validate untrusted input at boundaries.
+- Do not weaken compiler, lint, type, test, or security settings to get a pass.
+- Add tests for behavior changes and regression fixes. Payment-related changes
+  select applicable cases from `.agent/TEST_MATRIX.md`.
 - Do not leave dead code, unexplained suppressions, placeholder credentials, or
-  untracked follow-up work hidden in comments.
-- Update documentation when behavior or architectural patterns change.
+  hidden follow-up work.
+- Update documentation when behavior, contracts, or architecture change.
 
-## Quality policy
+## Repository skills
 
-Before Review Gate A, run the full local validation suite:
+- `oneshot-idempotency`: mandatory for intent, retry, worker, payment,
+  reconciliation, or settlement work.
+- `oneshot-failure-injection`: mandatory for external-effect failure
+  boundaries.
+- `sponsor-qualification`: mandatory before sponsor, demo, or release claims.
 
-```bash
-# Project quality checks (configure as codebase components are introduced)
-# e.g., lint, type check, unit tests, integration checks
-```
+Personal workflow and review skills may supplement these rules. They never
+replace OneShot policy or FreePi Gate A/B.
 
-Run additional focused tests required by the changed subsystem. A passing build
-does not replace behavioral tests, security checks, or manual verification.
-
-Do not bypass a failed check with `--force`, `--no-verify`, broad ignore rules,
-lowered thresholds, or dependency overrides. Fix the cause or document a genuine
-blocker for the user.
-
-## Git and GitHub
+## Git and review policy
 
 - Never implement directly on `main` or `develop`.
-- The default development and integration branch is `develop`.
-- All milestone and feature pull requests must target `develop`.
-- Use a descriptive branch such as `milestone/<id>-<name>`, `feature/<name>`, or
-  `fix/<name>`.
-- Never force-push, delete a protected branch, rewrite shared history, or use a
-  destructive reset without explicit user authorization.
-- Stage only files belonging to the active milestone and review the staged diff
-  before committing.
-- Draft pull requests may be created only after Review Gate A passes.
-- A draft may be marked ready for user review only after required CI and Review
-  Gate B pass for the exact current head commit.
-- Agents must never merge a pull request. The user performs the final review and
-  explicitly decides whether to merge.
-
-## Mandatory independent reviews
-
-Follow `.agent/MILESTONE_IMPLEMENTATION_LOOP.md` exactly.
-
-- Review Gate A is a fresh, independent review of the complete workspace change
-  before the draft pull request is created. It evaluates the staged candidate
-  tree against the exact target base SHA, covering acceptance criteria,
-  correctness, edge cases, security, and test coverage.
-- Review Gate B is a second fresh, independent review after the draft PR exists
-  and required CI is green. Gate B is bound to the exact PR head commit SHA and verifies
-  PR readiness, diff integrity, and check results.
-- The implementation agent must not act as its own independent reviewer. Reviewers
-  must be invoked in an independent session using `.agent/review-prompts/implementation-review.md`
-  for Gate A and `.agent/review-prompts/draft-pr-review.md` for Gate B.
-- No specific review vendor or model is mandatory unless a milestone explicitly
-  requires one. Missing reviewer tool or reviewed Git identity is a failure.
-- Do not reuse or resume the Gate A session for Gate B.
-- Any content change after Gate A invalidates Gate A.
-- Any commit after Gate B invalidates Gate B.
-- `WARN`, an incomplete response, unavailable tooling, authentication failure,
-  or an ambiguous verdict is not a pass.
-
-## Security, privacy, and secrets
-
-- Never commit secrets, API keys, tokens, credentials, private certificates, or personal data.
-- Maintain a comprehensive `.gitignore` for secrets, local environments, and temporary artifacts.
-- Validate input sizes and payloads before running expensive operations.
-- Treat dependency and code licensing as core release criteria.
-
-## Definition of agent-complete
-
-Work is ready for user review only when:
-
-- Milestone acceptance criteria are fully met;
-- The branch contains only intended changes;
-- Local checks and required GitHub checks pass;
-- Review Gate A and Review Gate B pass for the current head commit;
-- All blocking findings are fixed and re-reviewed;
-- The draft PR has been marked ready, but not merged;
-- The PR description details scope, risk, validation evidence, and both review verdicts;
-- Documentation is updated and accurate.
-
-When handing off, report the branch, commit SHA, PR URL, checks run, review verdicts,
-known limitations, and the exact decision required from the user.
+- Branch from current `develop`; target `develop` from short-lived
+  `feature/*`, `fix/*`, or `milestone/*` branches unless the user explicitly
+  names another short-lived branch.
+- Never direct-push or force-push protected branches or rewrite shared history
+  without explicit user authorization.
+- Follow `.agent/IMPLEMENTATION_LOOP.md` for local checks, staged-tree identity,
+  both independent FreePi reviews, CI, PR readiness, and invalidation rules.
+- Only explicit `VERDICT: PASS` passes a gate. Missing, ambiguous, truncated,
+  stale, unauthenticated, or failed review output fails closed.
+- Agents never merge a PR. A human reviews and explicitly authorizes the merge.
+
+## Context retention
+
+Follow `.agent/context/README.md`. Update the active record at milestone
+boundaries, before handoff/session end, and before deliberate context reset or
+compaction when possible. Never store secrets there.
+
+## Agent-complete
+
+Handoff only after intended scope is complete, local checks pass, the diff is
+cleanly scoped, and current gate state is recorded. A change is ready for human
+review only after Gate A, required CI, and Gate B pass for the exact applicable
+tree/head. Report branch, commit, PR, checks, gate evidence, and remaining
+risks. Never merge.

.agent/IMPLEMENTATION_LOOP.md

@@ -0,0 +1,144 @@
+# OneShot Implementation Loop
+
+This is the required path from a focused change to human review. `develop` is
+the base. Gate A binds to one immutable candidate tree before the first push;
+Gate B binds to the exact draft-PR head SHA and the same tree after required CI.
+
+## 1. Scope and branch
+
+1. Start from current `develop`.
+2. Create one short-lived `feature/*`, `fix/*`, or `milestone/*` branch unless
+   the user explicitly names another short-lived branch.
+3. Record goal, acceptance criteria, assumptions, non-goals, and branch state in
+   `.agent/context/`.
+4. Never implement directly on `develop` or `main`.
+
+## 2. Implement and validate
+
+1. Make the smallest coherent change.
+2. Use applicable repo skills and `.agent/TEST_MATRIX.md`.
+3. Run local format, lint, type, test, build, and focused failure-injection
+   checks that exist for affected components.
+4. Inspect tracked, staged, unstaged, ignored, and intended untracked changes
+   for scope, generated files, secrets, and unrelated work. Never open or send
+   ignored secret files to a reviewer.
+5. Stage every intended file and only intended files. Gate A reviews a single
+   candidate tree, not a partially staged workspace.
+6. Record concise command/result evidence in the active context. Keep full logs
+   only for failures that require diagnosis.
+
+Do not bypass failures with force flags, skipped checks, broad ignores, lower
+thresholds, or disabled hooks.
+
+## 3. Capture immutable Gate A evidence
+
+Refresh the base and record exact identities:
+
+```bash
+git fetch origin develop
+git rev-parse origin/develop
+git write-tree
+git status --short
+git diff --cached --check
+git diff --cached <recorded-base-sha>
+```
+
+- `recorded-base-sha` is the printed full SHA, not a moving ref.
+- `git write-tree` is the candidate tree SHA.
+- For an already-created but unpushed merge commit, use
+  `git rev-parse "HEAD^{tree}"` and `git diff <recorded-base-sha> HEAD`; the
+  commit must have no additional workspace changes.
+- Confirm no intended change is absent from the candidate and no unrelated file
+  is present.
+
+## 4. FreePi Gate A: pre-push review
+
+1. From the repository root, start exactly one fresh process:
+
+   ```bash
+   npx free-pi-cli
+   ```
+
+2. In one message, tell the new session to read
+   `.agent/review-prompts/freepi-prepush-review.md`; provide only the task
+   acceptance criteria, recorded base SHA, candidate tree SHA, and whether the
+   tree is staged or the exact unpushed `HEAD` tree.
+3. Let the reviewer inspect the candidate diff and routed repository documents
+   with its tools. Do not paste duplicate policy, complete file bodies, repeated
+   terminal output, or secrets into the prompt.
+4. Accept only an explicit `VERDICT: PASS` containing the required reviewer,
+   model, base, target, and tree identities.
+
+Each attempt uses a new `npx free-pi-cli` process. Never resume or reuse a
+reviewer context. Any candidate-tree change invalidates Gate A and requires
+local checks plus a new process. Missing evidence, ambiguity, truncation,
+authentication/tool failure, or any verdict other than explicit PASS fails
+closed.
+
+## 5. Commit, push, and draft PR
+
+Only after Gate A passes for the candidate tree:
+
+1. If the tree is staged, commit it without changing content. If Gate A reviewed
+   an existing unpushed commit, do not amend it.
+2. Confirm `git rev-parse "HEAD^{tree}"` equals the reviewed candidate tree.
+3. Push the short-lived branch without force.
+4. Create a draft PR targeting `develop`, never `main` for feature work.
+5. Fill `.github/PULL_REQUEST_TEMPLATE.md`, including Gate A evidence.
+
+## 6. Required CI
+
+Wait for every required check on the exact draft-PR head SHA. Pending, skipped,
+missing, or failing required checks are not green.
+
+If a fix changes content, rerun local validation and fresh Gate A, commit, push,
+and wait for CI again.
+
+## 7. FreePi Gate B: exact PR review
+
+1. Capture PR URL/number, base, head branch, exact full head SHA, head tree SHA,
+   full diff, required check results, and Gate A candidate tree.
+2. Start a second fresh process from the repository root:
+
+   ```bash
+   npx free-pi-cli
+   ```
+
+3. In one message, tell it to read
+   `.agent/review-prompts/freepi-pr-review.md` and provide only the captured
+   identities, PR URL, concise CI summary, acceptance criteria, and Gate A
+   verdict. Let the reviewer obtain the diff and public evidence with tools.
+4. Accept only explicit `VERDICT: PASS` bound to the exact current PR head SHA
+   whose tree equals the Gate A candidate tree.
+
+Any content change after Gate B invalidates both tree equality and Gate B.
+Return to local validation, fresh Gate A, commit/push, green CI, then fresh Gate
+B.
+
+## 8. Human review and merge
+
+After Gate A, required CI, and Gate B pass for the current tree/head:
+
+1. Record both verdicts and evidence in the PR and context file.
+2. Mark the draft ready for human review.
+3. Report branch, SHA, tree SHA, PR URL, checks, gates, and residual risks.
+4. Stop. Agents never merge; only a human may authorize and perform the merge.
+
+## Review token discipline
+
+- Canonical policy is linked, not copied into tool adapters or review prompts.
+- Send each reviewer one compact instruction message. The reviewer reads only
+  documents routed by root `AGENTS.md` and files relevant to the diff.
+- Reference immutable Git identities and concise check results instead of
+  pasting whole diffs, policy files, or successful logs into chat.
+- Reviewers inspect silently and return one structured verdict. They do not
+  narrate file reads, repeat the task, or restate unchanged policy.
+- Never reduce scope, skip evidence, or hide failures to save tokens. Token
+  discipline removes duplication, not review coverage.
+
+## Privacy boundary
+
+FreePi may review the candidate diff, tests, public documentation, and
+non-sensitive check evidence only. Never provide `.env*`, ignored files,
+private keys, seed phrases, access tokens, API secrets, wallet credentials, or
+sensitive runtime configuration. If safe review is impossible, fail the gate.