# iEvo Pipeline Context

> Cortex {{ cortex_version }} — auto-generated by `ievo init`. Auto-updated when CLI version changes.
> Do not edit manually — changes will be overwritten.

## Directory Structure

```
.ievo/
├── version           # CLI version that last updated this project
├── iEVO.md           # This file — pipeline context overlay
├── config.yaml       # Project settings
├── backlog/          # Raw ideas (IDEA-xxx) and research proposals (PROP-xxx)
├── spec/             # Requirements (REQ-xxx), questions (Q-xxx), changes (CR-xxx)
│   ├── SPEC_INDEX.md # Registry of all specs + statuses
│   ├── requirements/ # REQ-NNN-<slug>.md
│   ├── questions/    # Q-NNN-<slug>.md, Q-NNN-arch.md (escalations)
│   └── changes/      # CR-NNN-<slug>.md
├── plans/            # Implementation plans (PLAN-REQ-xxx)
├── reports/          # Verification results
│   ├── review/       # REVIEW-REQ-xxx.md (code review)
│   ├── qa/           # QA-REQ-xxx.md (QA testing)
│   ├── acceptance/   # ACC-REQ-xxx.md, ACC-REQ-xxx-rN.md (revisions)
│   ├── tech-lead/    # AUDIT-YYYY-MM-DD.md (infrastructure audits)
│   └── defrag/       # DEFRAG-YYYY-MM-DD.md
├── evolution/        # Evolution log + overlays (see EVOLUTION.md)
│   ├── LOG.md        # Append-only findings journal (write-only)
│   ├── KERNEL.md     # Kernel overlay — pipeline-level rules (read by all agents)
│   └── agents/       # Per-agent overlays
│       └── <agent>.md
└── memory/           # Shared project memory
    ├── CONTEXT.md    # Project state, entities, architecture
    ├── DECISIONS.md  # Append-only decision log
    ├── VOCABULARY.md # Domain terms and definitions
    ├── HISTORY.md    # Session index with statuses
    └── sessions/     # Per-session plan + log
        └── NNN/
            ├── plan.md
            └── log.md
```

## Document Lifecycle

```
Session starts → memory/sessions/NNN/plan.md (intent, goals, scope)
  │
  │  Idea → backlog/IDEA-xxx.md
  │    ↓ (Sprint planning — human selects)
  │  Spec Writer → spec/requirements/REQ-xxx.md
  │    ↓ (ambiguity?)
  │    → spec/questions/Q-xxx.md (blocks REQ until resolved)
  │    ↓
  │  Architect → plans/PLAN-REQ-xxx.md
  │    ↓ (plan broken?)
  │  Coder → spec/questions/Q-xxx-arch.md (escalation to Architect)
  │    ↓
  │  Coder → src/ + tests/ → push branch → open PR (/create-pr)
  │    ↓
  │  Direction Reviewer — right thing? PR description vs REQ criteria
  │    ↓ WRONG → Coder fixes → push
  │    ↓ PASS
  │  Architect Reviewer — built as designed? implementation vs PLAN
  │    ↓ WRONG → Q-xxx-arch.md → Coder fixes → push
  │    ↓ PASS
  │  Code Reviewer → reports/review/REVIEW-REQ-xxx.md
  │    ↓ NEEDS CHANGES → Coder fixes → push
  │    ↓ PASS
  │  QA → reports/qa/QA-REQ-xxx.md (+ additional tests)
  │    ↓ BUGS FOUND → Q-xxx-qa.md → Coder fixes → push
  │    ↓ PASS
  │  Acceptance (full) → reports/acceptance/ACC-REQ-xxx.md
  │    ↓ FAIL → Coder fixes → ACC-REQ-xxx-r2.md (revision)
  │    ↓ PASS → notify user → merge PR → status = implemented
  │    ↓
  │  Docs → docs/, README.md, CLAUDE.md
  │
Session ends → memory/sessions/NNN/log.md (reality, artifacts, commits)
            → memory/HISTORY.md updated
```

## Requirement Statuses

```
draft → ready → in-progress → review → implemented | blocked | removed
```

- `draft` — has ambiguities, not ready for implementation
- `ready` — fully specified, agent can pick it up
- `blocked` — agent found ambiguities, questions filed
- `in-progress` — agent is currently implementing
- `review` — implementation complete, in code review / QA / acceptance pipeline
- `implemented` — all acceptance criteria met, all tests passing
- `removed` — deleted via Change Request

## Sessions

A **session** is one episodic work unit — one sitting, one goal. Sessions wrap pipeline work and track what happened.

### Structure

```
memory/sessions/NNN/
├── plan.md   # Intent — written BEFORE work starts
└── log.md    # Reality — written during and after work
```

- **`plan.md`** — goals, phases, decisions to make, files to create/modify. This is the recovery document — if a session crashes mid-work, the plan enables another agent to continue.
- **`log.md`** — what was actually built, artifacts created/modified, commits, errors encountered, pending items. Updated incrementally as work progresses.

### Session statuses

```
planned → in_progress → completed
```

### HISTORY.md format

`memory/HISTORY.md` is the lightweight index of all sessions:

```markdown
| # | Date | Topic | Status | Key outcome |
|---|------|-------|--------|-------------|
| [001](sessions/001/) | 2026-02-28 | Project bootstrap | completed | Architecture decided, first 3 REQs |
| [002](sessions/002/) | 2026-03-01 | Auth implementation | in_progress | REQ-001 through REQ-005 |
```

### Rules

- **Plan first**: write `plan.md` BEFORE starting implementation. No plan = no recovery if context is lost.
- **Incremental updates**: update `plan.md` and `log.md` after each phase completes — don't wait until session end.
- **Sequential numbering**: 001, 002, 003... Never skip numbers.
- **One session = one goal**: if the goal shifts significantly, start a new session.

## Cross-Linking

How documents reference each other across the `.ievo/` structure.

### Sessions → Artifacts (strong, required)

`log.md` MUST list all artifacts created or modified during the session:

```markdown
## What was done
- Created: REQ-001, REQ-002, REQ-003
- Approved: PLAN-REQ-001
- Passed: ACC-REQ-001
- Decisions: D-007, D-008
- Commits: abc1234, def5678
```

### Artifacts → Sessions (weak, optional)

REQ, PLAN, and ACC files do NOT require session references. Artifacts are autonomous — they survive across multiple sessions and can be referenced independently. An optional `Created in: Session NNN` note is fine but never required.

### DECISIONS.md — the cross-session decision log

Decisions are referenced by ID (`D-NNN`) from any document:

```markdown
## D-007: Use PostgreSQL for persistence
**Date:** 2026-02-28
**Session:** 001
**Context:** Evaluated SQLite vs PostgreSQL vs MongoDB
**Decision:** PostgreSQL — team expertise, ACID guarantees
**Affects:** REQ-003, REQ-004
```

Decisions persist across sessions. When an agent needs to know WHY something was decided, it reads DECISIONS.md — not old session logs.

### Summary

| Direction | Strength | Example |
|-----------|----------|---------|
| Session → Artifacts | **Strong** | `log.md` lists REQ-001, PLAN-REQ-001, ACC-REQ-001 |
| Artifacts → Sessions | Weak | Optional "Created in Session 001" metadata |
| Any doc → Decisions | **Strong** | "Per D-007, we use PostgreSQL" |
| HISTORY.md → Sessions | **Strong** | Links to `sessions/NNN/` directories |

## Evolution Overlay

Project-specific lessons accumulate in `.ievo/evolution/` and are loaded as context at each session start. The evolution system has three components:

- **`LOG.md`** — append-only findings journal written by the Evolution agent. Write-only: agents do not load this as context.
- **`KERNEL.md`** — kernel overlay for pipeline-level lessons (naming conventions, document lifecycle, cross-agent coordination). Read by all agents at session start.
- **`agents/<agent>.md`** — per-agent overlay for agent-specific lessons. Read by that agent at session start.

```
Finding in agent behavior        → LOG.md + agents/<agent>.md
Finding in pipeline conventions  → LOG.md + KERNEL.md
All findings                     → curator GitHub issue
```

Read `EVOLUTION.md` for full convention — entry formats, routing rules, context loading template.

## Naming Conventions

| Type | Pattern | Location |
|------|---------|----------|
| Requirement | `REQ-NNN-<slug>.md` | `.ievo/spec/requirements/` |
| Question | `Q-NNN-<slug>.md` | `.ievo/spec/questions/` |
| Escalation | `Q-NNN-arch.md` | `.ievo/spec/questions/` |
| Change Request | `CR-NNN-<slug>.md` | `.ievo/spec/changes/` |
| Plan | `PLAN-REQ-NNN.md` | `.ievo/plans/` |
| Acceptance Report | `ACC-REQ-NNN.md` | `.ievo/reports/acceptance/` |
| Revision | `ACC-REQ-NNN-rN.md` | `.ievo/reports/acceptance/` |
| Code Review | `REVIEW-REQ-NNN.md` | `.ievo/reports/review/` |
| QA Report | `QA-REQ-NNN.md` | `.ievo/reports/qa/` |
| Tech Lead Audit | `AUDIT-YYYY-MM-DD.md` | `.ievo/reports/tech-lead/` |
| Defrag Report | `DEFRAG-YYYY-MM-DD.md` | `.ievo/reports/defrag/` |
| Idea | `IDEA-NNN-<slug>.md` | `.ievo/backlog/` |
| Proposal | `PROP-NNN-<slug>.md` | `.ievo/backlog/` |
| Session plan | `plan.md` | `.ievo/memory/sessions/NNN/` |
| Session log | `log.md` | `.ievo/memory/sessions/NNN/` |
| Session index | `HISTORY.md` | `.ievo/memory/` |
| Decision | `D-NNN` (entry in file) | `.ievo/memory/DECISIONS.md` |
| Evolution log | `LOG.md` | `.ievo/evolution/` |
| Kernel overlay | `KERNEL.md` | `.ievo/evolution/` |
| Agent overlay | `<agent>.md` | `.ievo/evolution/agents/` |

## Pipeline Rules

- **Language**: Communicate with the user in their language. All artifacts (specs, plans, reports, code, comments, documentation) are written in English
- **15-minute rule**: Architect decomposes every task to ≤15 minutes of agent work
- **Sprint = agreed REQs**: human approves what enters sprint. Scope is frozen once agreed
- **Backlog = pre-spec**: raw ideas and proposals, not yet refined into requirements
- **Acceptance loop**: FAIL → Coder fixes → Acceptance re-verifies. No shortcuts
- **Coder escalation**: plan broken → `Q-xxx-arch.md` → Architect revises plan
- **Evolution gates**: Evolution agent observes every pipeline transition (post-spec, post-plan, post-implementation, post-acceptance)
- **Atomic REQs**: each requirement has 3-7 testable acceptance criteria
- **Priority scoring**: `score = (priority_weight×3) + (blocking_count×2) + (dependency_met×1) - (complexity×0.5) - (open_questions×5)`. Weights: critical=10, high=7, medium=5, low=3. Rules: CRs before REQs → filter `ready` + deps `implemented` → score → tiebreak by lower REQ number. Agents auto-select highest-value task
- **Commit authorship**: all agent commits use `Co-Authored-By: iEVO <agent-name> <noreply@ievo.ai>` — never use the default Claude Code footer
- **Three-layer separation**: `CLAUDE.md` = project context (tech stack, architecture). `.ievo/iEVO.md` = pipeline conventions. `agents/*.md` = agent rules. NEVER write pipeline rules or evolution lessons to `CLAUDE.md` — they belong in agent `.md` files or `.ievo/evolution/agents/` (per-agent) / `.ievo/evolution/KERNEL.md` (pipeline)

## Best Practices

Proven practices derived from real sessions — apply these by default.

> New practices discovered during sessions go to `.ievo/evolution/KERNEL.md`, not here. See `EVOLUTION.md` for the full evolution convention.

### Requirements & Backlog

- **Discussion starts in backlog**: every new requirement begins as an `IDEA-NNN` entry in `.ievo/backlog/`, never directly as a REQ. The IDEA file is a living document — it grows through research, interview, and architect assessment until the judge promotes it to REQ.
- **Always record WHY**: every decision made during discussion must be logged with context — what options were considered, why this one was chosen, who decided. Log to IDEA file or `.ievo/memory/DECISIONS.md`. Without a decision log, context is lost within days and no one remembers why things were done a certain way.
- **Backlog revival requires full context reload**: when an idea returns from backlog after weeks, always load its discussion log and run a context refresh — what has changed since then, is the original approach still valid?
- **New requirements during discussion → new IDEA**: if a new requirement emerges during spec elicitation, capture it as a separate IDEA immediately. Do not graft it onto the current requirement's scope without explicit user approval.

### Research

- **Verify before trusting research findings**: always check that GitHub repos, star counts, and project names found in research are real. Researchers can hallucinate project names. Apply the "can I open this URL?" test. Flag unverified items with `⚠️ TODO: verify`.
- **Study adjacent ecosystems**: before building something, check if OpenClaw, IronClaw, Lobster, or similar projects already solved it. Reference implementations save months.
- **Persist research findings in `.ievo/research/`**: raw research output belongs in `.ievo/research/YYYY-MM-DD-<topic>.md`, not in backlog files or session logs. Backlog files (`IDEA-NNN`, `PROP-NNN`) reference research files — they don't contain raw findings. Update `INDEX.md` in `.ievo/research/` after every new research file. Format: `findings / comparing A vs B and why / conclusion / final decision and why`.

### Pipeline Design

- **Deterministic engine over LLM routing**: pipeline stage transitions must be driven by a deterministic workflow engine (YAML state machine), not by LLMs deciding what to do next. LLMs are unreliable routers — they misinterpret iteration counts and forget to signal transitions.
- **Hard gates between stages**: every pipeline stage has explicit entry conditions and exit artifacts. The next stage agent checks entry conditions before starting. No stage can claim completion without producing its required artifact.
- **Judge/gate agent is non-bypassable**: the judge that promotes a REQ from draft to ready cannot be skipped. If a stage's artifact is missing or invalid, the pipeline stops — it does not proceed with assumptions.

### Security

- **LLM sees credential names, never values**: inject only the list of available credential names into agent context. Actual values are resolved by the security layer at tool execution time and never appear in LLM reasoning.
- **LiteLLM proxy for API keys**: run a LiteLLM proxy on the host. Docker containers receive a fake API key + proxy base URL. The proxy adds real auth headers. Even `echo $ANTHROPIC_API_KEY` in the container returns a useless placeholder.
- **Shell wrapper over PTY bridge for credential injection**: replace `/bin/bash` inside Docker with `ievo-bash`. Intercept credential references at shell execution level — not at PTY stream level. PTY bridge fails during model thinking phases; shell wrapper fires on every actual tool execution regardless of model state.
- **Scan tool output for leaks**: PostToolUse hook (or shell wrapper post-exec) scans every tool output for credential patterns before returning it to the LLM.

### PR Review Methodology

All agents that review PR changes follow this protocol:

1. **Get changed files locally** — never use `gh pr diff` (GitHub has a 20 000-line limit):
   ```bash
   git fetch origin <branch>
   git diff main...<branch> --name-only
   ```

2. **Read each changed file by size**:
   - File < 300 lines → read the full file (`Read` tool)
   - File ≥ 300 lines → `git diff -U40 main...<branch> -- <file>` (40 lines context each side)

3. **Group files by module** before reviewing — understand the structure before diving into individual files

4. **Never review a raw diff alone** — a diff without surrounding context hides intent. When a single line changed, read at least the enclosing function.

### Agent & App Design

- **One agent, one responsibility**: each agent has exactly one job. Do not combine review, verification, and acceptance into one agent — split them. When an agent's description requires "and", it is two agents. Single-responsibility agents are independently replaceable, testable, and evolvable.
- **Apps > agents for end-to-end workflows**: when a use case requires multiple agents working together, package them as an iEvo App (agents + pipeline + MCP) rather than shipping loose agents. Users get a working system, not parts to wire manually.
- **One pipeline engine, many providers**: pipeline YAML is provider-agnostic. The same workflow runs whether agents execute on Claude, Codex, Ollama, or a mix. Provider selection lives in UAF agent config, not in pipeline logic.
- **Native CLI passthrough**: never replace the native provider CLI (Claude Code, Codex). Wrap it transparently via PTY bridge. Users keep full native access; iEvo adds orchestration on top.

