AGENTS.md git:20260925.02fad65A

Immutable. This exact content never changes and is served at /api/v1/blob/f98abfac23eb3ffb.

# ripwire — agent instructions

This repository follows the `AGENTS.md` convention. The full agent guide is **`CLAUDE.md`**; this
file is the short form, and the two do not disagree.

`ripwire` is a zero-runtime-dependency C++23 CLI that parses a codebase, ranks symbols by
Personalized PageRank, and streams a deterministic minified XML map to stdout.

## Setup

```bash
cmake -S . -B build && cmake --build build -j
```

No build type. `-DCMAKE_BUILD_TYPE=Release` defines `NDEBUG`, which compiles the
`DISCLOSE( msg )` trace out and blinds every degrade-path gate. CI builds both flavours; locally, use the plain one.

## Test

```bash
python3 test/pargates.py . ./build/ripwire -j 6     # full gate suite, parallel — run in the foreground
t=$(mktemp -d); ./build/ripwire . >"$t/a"; ./build/ripwire . >"$t/b"; diff -q "$t/a" "$t/b"   # determinism: byte-identical (outputs OUTSIDE the crawled tree)
./build/ripwire . | xmllint --noout -                     # XML well-formedness
```

Sanitizer build, required before a PR:

```bash
cmake -S . -B asan -DRIPWIRE_ASAN=ON && cmake --build asan -j
LSAN_OPTIONS=suppressions=lsan_suppressions.txt ./asan/ripwire . >/dev/null
```

A new `test/*check.sh` must be added to `test/regression.sh` in the same commit, or
`test/manifestcheck.sh` fails.

## Rules that will fail your change if you break them

- **Gate first, code second.** Rankings and call graphs look plausible whether or not they are right.
- **Determinism.** Sorted crawl order before ID assignment; fixed-block reductions in canonical
  order; no floating-point reassociation in the PageRank translation unit.
- **Honest output.** Floors are labelled `counts_floor="1"`; a zero is "none found", not "none
  exists"; every truncation is disclosed. Do not add a surface that rounds or guesses silently.
- **`ASSUME( cond )` for invariants; `DISCLOSE( sink, why )` for recoverable errors (the sink sets the output field that tells the reader; `DISCLOSE( msg )` alone ships nothing); `PANIC` for
  corruption.** Never `ASSUME( false )` on a degrade path — release deletes the fallback behind it.
- **No `std::map` / `std::unordered_map`** — `HashMap<>` for hash lookup, `gtl::btree_map` for
  ordered iteration, `dynamic_map` for bounded hot paths.
- **Allman braces, spaces inside parens** (`f( x )`), ~160–200 column wraps, index-vs-count naming
  (`nodeId` vs `nodeCount`).

## Documentation

| Need | File |
| --- | --- |
| Full C++ style, guardrails G1–G5, submission checklist | `CONTRIBUTING.md` |
| Pipeline, data model, determinism contract | `docs/ARCHITECTURE.md` |
| Measured claims and their provenance | `docs/EVALS.md` |
| Per-verb reference (generated from the binary) | `docs/COMMANDS.md` |
| Index of everything under `docs/` | `docs/README.md` |
| The authoritative flag list | `./build/ripwire --help` |

`--help` is generated from the binary. If a document disagrees with it, the document is the bug.