---
description: Brick repository supplement — evidence lanes, graph schema, and validation.
argument-hint: "[TASK=<description>] [PHASE=<start|checkpoint|complete>]"
---

# Brick agent instructions

The operating loop lives in docs/prompts/PROMPT-eng-codex.md. The
Brick-specific design and measurement flow lives in
docs/prompts/PROMPT-brick-engineering.md. Keep generic agent behavior there and
repository invariants here.

## Product contract

Brick turns source structure and imported analyzer evidence into a versioned,
inspectable building model:

    source tree -> extractors -> canonical graph -> metrics -> JSON + web view
                              ^ imported Fold/YAMS evidence

The JSON model is the product boundary. The renderer is a consumer. Do not
couple analysis correctness to Cytoscape or a specific layout algorithm.

## Evidence boundaries

- Preserve syntactic, symbolic, imported, and heuristic lanes.
- Every non-containment edge carries backend, confidence, and provenance.
- A Fold proved result means proved within Fold's bounded model; do not relabel
  it as universally true.
- Lexical extraction is conservative and heuristic. Never silently upgrade its
  confidence when a name resolves.
- Unknown wire values stay unknown or produce diagnostics; do not map them to a
  convenient known type.

## Stable identity and schema

- schema_version changes when readers need new behavior.
- IDs derive from kind plus stable repository-relative identity.
- JSON key names live in src/model.rs and are written by serde.
- Sort nodes and edges before serialization so unchanged inputs are reproducible.
- Paths in output are repository-relative except the top-level root field.

## Engineering loop

1. Name one observable graph behavior.
2. Add a focused Rust test with a positive and clean-negative fixture.
3. Implement the smallest extractor/model/metric change.
4. Run cargo fmt, focused tests, clippy, then the quality gate.
5. For score or extractor claims, run the benchmark plan at least three times
   and preserve the run manifest plus raw JSON.

## Validation

Brick pins the same `nightly-2026-05-28` compiler used by Fold's Rust analyzer.
Do not replace it with floating stable/nightly CI configuration without first
proving the crate-level Fold scan still has compatible dependency metadata.

    cargo fmt --check
    cargo test
    cargo clippy --all-targets -- -D warnings
    ./scripts/quality-gate.sh
    python3 tests/benchmarks/runner.py self-test

Do not promote an experimental health-weight change using Brick's own source
alone. Use labeled positive and clean-negative fixtures and describe expected
identity/metric deltas first.