# Agent verify loop shared reference

## Traceability

- Spec ID: agent-verify-loop-reference
- Status: Implemented

## Intent

Add a shared prose reference, `references/project-harness/agent-verify-loop.md`,
that teaches teams how to design the verification harness for a coding-agent
loop in a long-chain system (many entrypoints, many write targets, long
asynchronous paths). The reference generalizes a recurring field pattern —
data-driven case discovery, a reusable regression skeleton, parameterized
verification probes, and diff-scoped incremental plans — into one
implementation-neutral framework, and wires it into the existing workflow
consumers that already route verification design questions.

## Acceptance Scenarios

- **AVL-AC-1 (four planes):** The reference defines the Discover, Exercise,
  Judge, and Scope planes, each with one question and one durable asset, plus a
  bootstrap order that starts from a tracer-bullet case and the extracted
  probe.
- **AVL-AC-2 (verdict honesty):** The probe verdict domain is
  `pass | fail | unobserved | blocked`; missing evidence never maps to `pass`,
  and the aggregate plan verdict follows the weakest matched case so skipped
  or blocked coverage demotes the run to `blocked` or `partial` instead of
  producing a green result.
- **AVL-AC-3 (async bounds):** The probe contract requires a terminal
  condition, deadline, and polling/backoff policy for asynchronous chains, and
  distinguishes not-yet-observed evidence from failure.
- **AVL-AC-4 (data-access boundary):** The bootstrap path defaults to test data
  or sanitized fixtures; reading staging or production data requires explicit
  authorization, read-only scope, redaction, and an agreed environment
  boundary recorded in case `constraints`.
- **AVL-AC-5 (failure-to-regression):** Diagnosed-and-repaired failures become
  candidate cases that enter the regression skeleton through the same human
  value gate as discovered cases.
- **AVL-AC-6 (consumer wiring):** At least two visible workflow consumers
  route to the reference: the Agent Work Loop Change Validation dimension
  (`models/agent-work-loop.md`) and the Loop Blueprint independent-verifier
  envelope (`references/loop-engineering/loop-blueprint.md`), in addition to
  the `references/project-harness/README.md` directory index.
- **AVL-AC-7 (link integrity):** All relative links to and from the reference
  resolve, and the doc-link routing graph stays current.

## Non-goals

- Build a verification runtime, probe protocol, debugger/replay adapter, or
  any executable tooling; the reference stays implementation-neutral prose.
- Own loop owner selection, the full loop runtime contract, recovery
  evidence, or review-trigger policy; those stay with their existing owners.
- Prescribe vendor-specific technology (specific debuggers, tracing stacks,
  or record/replay products).
- Change scoring models, report schemas, skills, scripts, or templates.

## Plan and Tasks

1. Add `references/project-harness/agent-verify-loop.md` with the four planes,
   an overview mermaid flow, the verdict domain and aggregate rules, the
   regression-skeleton asset shape, the human value gate, rollout staging, and
   anti-patterns.
2. Register the reference in `references/project-harness/README.md` under
   `Owns` and `Read Next`.
3. Wire the two workflow consumers: the Change Validation routing paragraph
   and reference-ownership table in `models/agent-work-loop.md`, and the
   independent-verifier envelope item in
   `references/loop-engineering/loop-blueprint.md`.
4. Regenerate the doc-link routing graph and run the doc-link test, then the
   full repository suite.

## Test and Review Evidence

- `node --test test/doc-link-graph.test.mjs` — relative link resolution and
  routing-graph freshness.
- `npm test` — full repository suite.
- Review fixes applied before landing: production-data access boundary
  (AVL-AC-4), blocked-case aggregate verdict (AVL-AC-2), asynchronous probe
  bounds (AVL-AC-3), and consumer wiring (AVL-AC-6).