414a53f4d5
All checks were successful
deploy / deploy (push) Successful in 26s
Proof: Deployment repair may use kubectl only when the same fix is backported into repo workflow or scripts in the same turn, keeping push-driven automation as the steady-state path. Assumptions: Emergency break-glass incidents remain rare exceptions and should not redefine the normal deployment workflow. Still fake: Repo automation should prevent routine kubectl repair, but that guarantee depends on continued verification of the push-driven deploy path.
167 lines
8 KiB
Markdown
167 lines
8 KiB
Markdown
# 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.
|
|
- The repository must be fully wired so every service deploys automatically from a repo push.
|
|
- Manual deployment intervention is forbidden by default.
|
|
- `kubectl` may be used to fix a deployment only if the same fix is also backported into the repository scripts or workflow in the same turn so the next push should not require the same manual repair.
|
|
- Manual `kubectl` rollout, image patching, or other ad hoc production reconciliation without a repo backport is forbidden except when the user explicitly asks for emergency break-glass incident handling.
|
|
- 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
|
|
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
|
|
- deploying all repo-owned services automatically from push-driven repo workflow without manual cluster intervention
|
|
- 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.
|