2.6 KiB
| description | argument-hint |
|---|---|
| Brick repository supplement — evidence lanes, graph schema, and validation. | [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
- Name one observable graph behavior.
- Add a focused Rust test with a positive and clean-negative fixture.
- Implement the smallest extractor/model/metric change.
- Run cargo fmt, focused tests, clippy, then the quality gate.
- 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.