# volva-context

Codex's working root when invoked by the [Volva](https://gitea.phasefinal.com/vh/volva) daemon. Volva makes `codex` a peer on the althing bus; this directory is the durable context codex reads on every call.

## Why a separate repo

Volva's daemon repo (`~/development/volva`) deliberately keeps codex out of its own view — codex's CWD is here (`~/development/volva-context/`), not the volva repo. That isolation:

- Lets codex's context evolve on its own version track (this repo) without churning the daemon repo.
- Keeps codex from grepping the daemon's source while answering caller questions.
- Lets the operator update glossaries/inventories without touching daemon code.

The `VOLVA_CODEX_CWD` env var in `~/development/volva/env.sh` points here.

## Layout

```
.
├── AGENTS.md                  # codex's bootstrap entrypoint (read every call)
├── CONTEXT.md                 # Corviduo + Vast Blue glossary
├── INVENTORY.md               # project list, paths, gitea sources, role
├── PRINCIPLES.md              # the four engineering principles
├── REVIEW-GUIDE.md            # code-review discipline (one of two roles)
├── RESEARCH-PARTNER-GUIDE.md  # research-partner discipline (the other)
└── transient/
    ├── README.md              # per-call context convention
    └── *.md                   # caller-seeded transient files (gitignored)
```

## Roles

Volva operates in one of two roles per call, inferred from the caller's handle and the message body:

- **Research partner** when `brokkr-smithy-dev` asks for SOTA / probe-design / hypothesis-critique / methodology review.
- **Code reviewer** when a project-dev handle asks for diff review, contract review, ADR critique.

`AGENTS.md` is the entrypoint; the role guides are loaded as needed.

## Updating

This repo is durable but mutable. When project state changes:

- New project lands in Corviduo → extend `INVENTORY.md` + add an entry to `CONTEXT.md`.
- Glossary term shifts → update `CONTEXT.md` directly.
- New review-pattern or research-discipline lesson surfaces → extend the relevant role guide.
- Engineering principle clarification → update `PRINCIPLES.md`; this is the local copy of the operator-level lodestar.

Per-call ephemera goes in `transient/<slug>.md` (gitignored). See `transient/README.md` for the convention.

## Authority

Project-local `CONTEXT.md` files (in individual project repos) shadow entries here on conflict — most-local-wins. The definitions in this repo are the user-level baseline that Volva carries across calls.

Attribution: operator is Vuong Hoang. No AI / Claude / Anthropic / Codex attribution in artifacts Volva produces.