66 lines
2.6 KiB
Markdown
66 lines
2.6 KiB
Markdown
---
|
|
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.
|