<!-- foyer-docs · surface=agent · slug=/concepts · human=https://docs.getfoyer.dev/concepts · index=https://docs.getfoyer.dev/llms.txt -->
---
title: Concepts
description: The vocabulary Foyer uses — intent, signals, repair prompts, and how a verification runs.
---

Foyer's PR comment and CLI output use a small vocabulary repeatedly. This
page defines each term once, in order of when you'll meet it.

## Verification

A single run of the merge-readiness gate against one PR head SHA. Triggered
by a GitHub webhook (`pull_request: opened | synchronize | reopened`) or
manually via the CLI. A verification produces one PR comment and, on
failure, one repair prompt per failed signal.

## Signal

One verification check. Each signal returns `passed | warning | failed |
unavailable | unsupported_on_provider` plus a summary, evidence rows, and
(when failed) a repair prompt. The eleven shipped signals are catalogued
at [Signals](/agents/signals).

`unavailable` means the signal couldn't run (e.g. no test runner detected,
abort during install). `unsupported_on_provider` means the signal is
GitHub-only and you're on GitLab. Both are real, deliberate values — Foyer
never silently skips a signal.

## Intent

The PR's stated requirements, captured from one of:

1. A Linear issue linked to the branch (`foyer review --linear ENG-123`,
   or auto-detected by branch name).
2. A GitHub issue referenced in the PR body.
3. The PR body itself.
4. A pasted spec.
5. A plan artifact attached via `foyer plan attach` or `foyer plan save`.

Intent is split into atomic, verifiable requirements by an LLM at
intent-build time. Each requirement is scored independently.

## `scope_alignment`

The signal that scores the diff against the PR's intent. For each
requirement, the judge decides: was this implemented (`met`), partially
implemented, or missed. The verdict is one of `exact`, `superset`,
`subset`, `divergent`. A `divergent` verdict is the most common reason a
PR comment goes red.

This is Foyer's headline differentiator vs. CodeRabbit / Greptile / Bugbot.
They review code in isolation; Foyer reviews whether the code did what you
asked. Scope validation is the gate — the other ten signals back it up.

## Evidence

Per-signal proof attached to the result. Five kinds: `log`, `screenshot`,
`command`, `diff`, `repro`. The PR comment renders evidence rows under
each signal. The repair prompt's `context.evidence` mirrors them so the
fixing agent doesn't need to re-investigate.

## Repair prompt

Every failed signal carries one — a structured handoff the agent can
apply directly. Shaped:

```ts
interface RepairPrompt {
  prompt: string;
  context: Record<string, unknown>;
}
```

The `prompt` is a plain-markdown instruction that any coding agent
(Claude Code, Codex, Cursor, Windsurf, …) can consume. The `context`
carries failed-signal evidence, head SHA, file paths, and reproduction
commands. Drop it into your agent, the agent fixes the issue, you push,
next verification confirms green.

## Audience

Foyer supports two output voices:

- `technical` (default) — runner summaries assume the reader writes code.
- `non_technical` — same signals, plain-English summaries. Used for
  "show me what's wrong" views for non-engineering stakeholders.

The repair prompt always reads the technical summary; only the PR comment
swaps copy.

## See also

- [Signals](/agents/signals) — the per-signal reference.
- [CLI reference](/agents/cli) — invoke a verification locally with `foyer review`.
- [MCP server](/agents/mcp) — pull intent, evidence, and repair prompts into your agent.


---

[agent navigation]

- prev: https://docs.getfoyer.dev/agents/mcp
- next: https://docs.getfoyer.dev/agents/signals
- index: https://docs.getfoyer.dev/llms.txt
- human: https://docs.getfoyer.dev/concepts