> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironbee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Verification Context
> Give your agent area-specific verification instructions by dropping .ironbee/VERIFICATION.md files in your repo.
Different parts of a codebase need different things checked. A payments module wants the 3DS challenge exercised; an auth module wants session-fixation verified; the frontend wants an accessibility pass. **Verification context** lets your team author that guidance once, in the repo, and have IronBee surface *only the parts relevant to what changed*, injecting them straight into the agent's context the moment it starts verifying.
It's advisory: the guidance reaches the agent as a first-class reminder alongside the standard verification flow, but it never blocks completion on its own.
***
## Author guidance in `.ironbee/VERIFICATION.md`
Drop a Markdown file at `.ironbee/VERIFICATION.md` inside any directory whose changes need special attention:
```
my-app/
├── .ironbee/
│ └── VERIFICATION.md # repo-wide defaults
├── payment/
│ ├── .ironbee/
│ │ └── VERIFICATION.md # payment-area guidance
│ └── stripe/
│ └── charge.ts
└── frontend/
└── .ironbee/
└── VERIFICATION.md # frontend-area guidance
```
The file is plain prose. Write whatever you'd tell a teammate before they verify a change in that area:
```markdown theme={null}
# Payment verification
- Exercise the 3DS challenge flow end-to-end, not just the happy path.
- Confirm a declined card surfaces the retry UI, not a 500.
- Check that the idempotency key prevents a double charge on retry.
```
The file name is the fixed convention `.ironbee/VERIFICATION.md`; it isn't configurable. The `.ironbee/` folder is the same namespace that holds the project's `config.json` at the repo root, so area guidance lives alongside it consistently. These files are meant to be **committed** and reviewed in PRs; only `sessions/` and `config.local.json` are gitignored.
***
## How guidance is matched to a change
When a verification cycle begins, IronBee looks at **what changed this cycle**, then for each changed file walks *up* from its directory to the project root, collecting every `.ironbee/VERIFICATION.md` it finds along the way:
```
Changed: payment/stripe/charge.ts
Collects: payment/stripe/.ironbee/VERIFICATION.md (if present)
payment/.ironbee/VERIFICATION.md (if present)
.ironbee/VERIFICATION.md (repo-wide default, if present)
```
* **Nearest-parent hierarchy:** a change picks up its own area's guidance plus everything above it. Directories without a file are simply skipped.
* **Merged general → specific:** the repo-wide default reads first, area-specific guidance after it.
* **Deduplicated:** if ten files under `payment/` changed, `payment/.ironbee/VERIFICATION.md` is included once.
* **Always includes the changed-path list:** even when *no* `.ironbee/VERIFICATION.md` matches, IronBee still injects the list of paths that changed this cycle (capped at 100, with a `+N more` for the rest). This gives the delegated verifier a head start on *what* to exercise instead of discovering it from scratch. Authored guidance, when present, is appended on top.
***
## An always-on instruction (`verification.context.message`)
The `.ironbee/VERIFICATION.md` files are *path-scoped* — they only reach the verifier when a change touches their directory. For a standing instruction that should accompany **every** verification cycle regardless of what changed, set `verification.context.message`:
```bash theme={null}
ironbee config set verification.context.message "Confirm the health endpoint returns 200 before passing."
```
This is injected into every cycle **unconditionally** — even a manual `/ironbee-verify` with no code changes, where the changed-path list and path-scoped docs would otherwise be empty. It's rendered first, ahead of any matched `VERIFICATION.md` guidance, and is **never truncated** (it reserves its own bytes so the `maxBytes` cap still bounds the path-scoped docs).
Two value forms:
* **Inline text** the message itself.
* **A file reference** `file:`, read at verification time. The path is relative to the project dir; a leading `~` expands to your home directory; a missing or unreadable file is silently skipped.
```bash theme={null}
ironbee config set verification.context.message "file:.ironbee/verify-checklist.md"
```
Like the rest of the context keys, it's layered across global / project / local (the highest layer that sets it wins) and read live, so a change takes effect on the next session.
***
## What counts as "changed"
By default the changed set comes from **git**: your uncommitted work (working tree: staged, unstaged, and untracked files) plus the last commit. In a non-git project, IronBee falls back to its own `file_change` events for the current cycle.
* [`ignoredVerifyPatterns`](/cli/configuration/configuration#core-options) filter the set — test files are excluded by default, and anything you add filters out build/docs churn too, so it doesn't pull in guidance.
* IronBee's own `.ironbee/` tree is always excluded.
* `commitDepth` controls how many recent commits join the working tree: `1` (default) covers in-flight work plus the latest commit, `0` is uncommitted-only, and you can raise it for teams that commit per logical step.
***
## When it's injected
The guidance is injected on the **first verification tool call of each cycle** (exactly when the agent starts verifying) and once per cycle (re-verifying after a fix gets a fresh read of what changed). It arrives through each client's native context channel, so the agent treats it as a binding reminder, not incidental output.
| Mode | Injects? |
| ---------------------- | --------------------------------------------------------- |
| **Assist** *(default)* | Yes, manual `/ironbee-verify` cycles get the guidance too |
| **Enforce** | Yes |
| **Monitoring-only** | No, monitoring installs no verification hooks |
It is **advisory in this release**: the agent must follow the guidance as part of its verification, but the content itself never gates completion. (Machine-checkable per-area rules are planned separately.)
***
## Configuration
The feature is on by default. Tune it under the `verification.context` key. See [Configuration → Verification context](/cli/configuration/configuration#verification-context) for the full table. The common knobs:
```bash theme={null}
ironbee config set verification.context.enable false # turn it off entirely
ironbee config set verification.context.commitDepth 0 # uncommitted work only
ironbee config set verification.context.source actions # skip git, use IronBee's own file_change events
```
These keys are read live at verification time, so a change takes effect on the next session without re-rendering client artifacts.
`.ironbee/VERIFICATION.md` is repo content at the same trust level as `CLAUDE.md` or `AGENTS.md`; the agent follows whatever it says. Review changes to these files in PRs as you would any other instruction your agent reads.
***
## What's next?
Choose which platforms get verified and switch between enforce, assist, and monitoring.
The full `verification.context` key reference.