unrip/AGENTS.md

unrip agent rules

This repository is run with a data-first trading-system workflow.

Core rule

Every change must directly serve the currently approved turn.

What a turn is

A turn is the currently approved slice of work. There are two lanes:

• Implementation turn:
  • defined by PROOF.md and IMPLEMENTATION.md
  • the job is to implement what IMPLEMENTATION.md says, validate it against PROOF.md, and keep working until the scoped fake paths are removed or explicitly recorded as remaining blockers
• Research turn:
  • defined by research/ACTIVE.md
  • the job is to produce evidence against the active research charter, not product shape

BACKLOG.md is not the turn. ARCHIVE.md is not the turn. They are planning and history artifacts.

Read order by task

Use the smallest context needed for the current task.

For implementation work

Read only:

1. THESIS.md
2. PROOF.md
3. IMPLEMENTATION.md

Do not read BACKLOG.md, ARCHIVE.md, or research/ACTIVE.md during an implementation turn unless the user explicitly asks to re-plan, open a new turn, review history, or switch to research.

For research work

Read only:

1. THESIS.md
2. research/ACTIVE.md

Do not read BACKLOG.md, ARCHIVE.md, PROOF.md, or IMPLEMENTATION.md unless the user explicitly asks to re-plan, compare lanes, or promote research into implementation.

For planning, re-planning, or archiving

Read:

1. THESIS.md
2. the live turn files for the lane being changed
3. BACKLOG.md
4. ARCHIVE.md

Hard constraints

• Do not invent or adopt a new roadmap on your own.
• Do not expand scope beyond the active implementation proof or research charter.
• No backlog generation instead of implementation.
• No scaffolding ahead of demonstrated need.
• Quote collection and analytics are first-class from day one. They are not a later add-on.
• Do not present scaffolding, dashboards, placeholders, or mock flows as product progress.
• State assumptions before coding when the environment, venue, chain, or source behavior is uncertain.
• Declare what is still fake in every commit.
• Do not read BACKLOG.md or ARCHIVE.md during an implementation turn unless the user explicitly asks to re-plan, open a new turn, or inspect history.
• If you discover adjacent work, add it to BACKLOG.md instead of absorbing it into the current turn.
• Changes that widen risk require explicit user approval:
  • live funds
  • secret creation or rotation
  • permanent infrastructure spend
  • long-running external jobs
  • destructive data migrations
• The long-term thesis may be proposed, but THESIS.md must not be rewritten without explicit user approval.

Iteration archive rule

When the user says to plan the next iteration, next turn, implementation turn, or proof sprint:

• first preserve the finished turn before drafting new planning docs
• do not rewrite the live turn files until the current turn has been archived
• use the existing repo workflow and archive locations:
  • implementation turn snapshots go in archive/implementation/
  • research turn snapshots go in archive/research/
• prefer the tracked scripts:
  • python3 scripts/workflow/close_turn.py ...
  • python3 scripts/workflow/open_turn.py ...

Planning or archiving is the one time it is correct to read BACKLOG.md and ARCHIVE.md.

Planning inputs

• iteration, implementation turn, proof sprint, and next turn mean the same planning slice unless the user says otherwise.
• Use BACKLOG.md only while planning, re-planning, or archiving. Do not read it while implementing or validating the active turn unless the user explicitly asks.
• Select backlog items and bugs that belong together under one proof topic instead of mixing unrelated work into the same slice.
• When an item is pulled into the live turn, remove it from BACKLOG.md and record the planning event in ARCHIVE.md.

Planning quality bar

• IMPLEMENTATION.md must be detailed enough that coding does not depend on rediscovering the plan mid-turn.
• IMPLEMENTATION.md should cover the end-to-end system touched by the proof: ingest, pricing, inventory, persistence, strategy, execution, control surfaces, logging, validation, tests, failure modes, and important edge cases.
• PROOF.md must be specific and falsifiable: scope, non-goals, definition of done, validation evidence, failure conditions, and clear statements about what is real versus fake.
• Both planning documents should think through the whole operator workflow and full system path, not isolated file edits.

Turn lanes

• Implementation lane:
  • Governed by PROOF.md and IMPLEMENTATION.md.
  • Must make the shared live and historical data path more real unless the turn is explicitly marked as pure ops.
  • “Doing the turn” means implementing IMPLEMENTATION.md, validating against PROOF.md, fixing what fails, and continuing until the definition of done is met or a hard blocker is reached.
• Research lane:
  • Governed by research/ACTIVE.md.
  • Must name the hypothesis, dataset, metric, assumptions, and falsification condition.
  • Research output is evidence, not product shape.

Commit rules

Every non-merge commit message body must include:

• Proof: ...
• Assumptions: ...
• Still fake: ...

Install the tracked hook before relying on this:

bash scripts/workflow/install_hooks.sh

Post-implementation loop

• After implementation and validation, expect the user to test the slice and suggest small fixes.
• Treat those small fixes as part of closing the same turn unless the user explicitly changes scope.

Bug-fix rule

• If a bug is found, fix it, inspect analogous or affected locations, and apply the needed follow-up fixes there too.
• No bug fix is done without a regression test.
• If a meaningful automated test cannot be added, stop and explain why instead of claiming the fix is complete.

Real progress vs fake progress

Real progress means the repository can do more of the active proof with validated evidence from real systems. In this repo that means things like:

• ingesting real NEAR Intents flow
• storing durable inventory, pricing, decision, and execution records
• producing a real decision from live data
• making a real execution attempt through repo-controlled code
• proving blocked-path safety with explicit evidence

Fake progress includes:

• docs-only motion without stronger runtime truth
• speculative architecture not required by the active proof
• dashboards or control surfaces without the underlying real path
• placeholders or mocks presented as finished work
• invented data, unverifiable claims, or abstractions not yet required

Safety rules

• Prefer the smallest real implementation that proves the active turn works.
• Keep secrets out of git, docs, and chat history.
• Use self-hosted or directly controlled infrastructure by default.
• If something is fake or incomplete, say so plainly.

Review standard

Before claiming a turn is done, be able to state:

• what became more real
• what was validated against real data or systems
• what is still fake
• what was deliberately not built

Working rule

Within an approved turn, continue implementing and validating until:

• PROOF.md is satisfied for the active scope, or
• a hard blocker requires user input.

Do not silently open the next turn yourself. Do not stop at “the structure exists.” Do not stop while the active turn still depends on hidden dummy paths. If something remains fake at the end of the turn, name it plainly.