# WORKFLOW.md

AGENT_WORKFLOW uses nine gates. A task cannot be considered done unless each gate is completed or explicitly justified.

## Gate 1 — Understand

- Define the goal.
- Define non-goals.
- Define expected output.
- Identify project and task ID.
- Confirm constraints, data sensitivity and deployment target.

## Gate 2 — Search Existing Code

Use `rg`, `find`, `ls`, `tree` or equivalent commands.

Search for:

- existing functions
- schemas
- tests
- conventions
- configs
- scripts
- similar reports or ADRs

Document commands used and files found.

## Gate 3 — Reuse Decision

Choose exactly one:

- Reuse existing function.
- Modify existing function.
- Build small module.
- Stop because unnecessary.

The decision must include a reason. Building is allowed only when reuse or modification is not appropriate.

## Gate 4 — Minimal Design

Write a short design:

- files allowed to edit
- behavior change
- tests to run
- known risks
- rollback path if relevant

No global refactor without explicit task scope.

## Gate 5 — Implement Only Assigned Files

- Keep strict scope.
- Do not edit unrelated files.
- Do not perform global formatting unless requested.
- Do not rename public APIs unless the task requires it.
- Keep modules small and readable.

## Gate 6 — Tests

Run relevant tests:

- unit tests
- integration tests
- smoke tests
- lint/type checks when available

Document exact commands. If tests cannot run, explain why and what should be run next.

## Gate 7 — Anti-Leakage / Security Check

For temporal data:

- verify `available_at <= prediction_time`
- verify no future data enters features
- verify labels are not used as prediction features
- verify train/test split is temporal when needed
- verify backtests are walk-forward

For security:

- no secrets
- no tokens in logs
- no `.env` committed
- no direct port exposure unless justified
- no complete article/content storage without validation

Block the task if leakage or secret exposure is detected.

## Gate 8 — Task Report + Context Compression

Write `reports/task_reports/TASK_ID.md` with:

- goal
- non-goals
- summary
- files changed
- commands run
- tests
- reuse decision
- risks
- security/leakage check
- remaining work
- next recommended task

Update `PROJECT_STATE.md` with only durable information: decisions, changed files, current risks, next tasks and recent reports.

## Gate 9 — Review + Merge

Reviewer checklist:

- scope respected
- reuse decision documented
- tests pass or failure is understood
- no secrets
- no leakage
- docs updated
- task report complete
- project state updated

Merge is blocked if tests, leakage, security or scope checks fail.

## Mermaid Workflow

```mermaid
flowchart TD
    A[Gate 1 Understand] --> B[Gate 2 Search Existing Code]
    B --> C[Gate 3 Reuse Decision]
    C -->|reuse| D[Gate 4 Minimal Design]
    C -->|modify| D
    C -->|build small module| D
    C -->|stop unnecessary| R[Report Stop Decision]
    D --> E[Gate 5 Implement Assigned Files]
    E --> F[Gate 6 Tests]
    F --> G[Gate 7 Leakage and Security Check]
    G -->|pass| H[Gate 8 Task Report and Context Compression]
    G -->|fail| X[Block and Fix]
    X --> E
    H --> I[Gate 9 Review and Merge]
    I -->|approved| J[Merge]
    I -->|changes requested| E
```