behavior-diff
Captures each route's observable HTTP behavior before and after a change, then diffs in behavior-space so the human reviews six items, not a 5,000-line diff.
behavior-diff
ADLC phase: P6 Integrate · Gate: the reviewer sees what changed in observable behavior, not the raw code diff.
What it defends against
A large code diff hides its own consequences: the reviewer cannot tell, from 5,000
changed lines, which of them actually altered what a client observes. behavior-diff
captures the HTTP surface (status, content-type, body structure) of every route
before and after a change, then reports the delta in behavior-space: "2 routes
identical, 2 changed, 0 errored." The human spends the gate on the one judgment a
machine cannot make: does the observed behavior change match the intended one?
Usage
adlc behavior-diff capture --config behavior.json --out before.json [--json]
adlc behavior-diff compare before.json after.json [--json]| Verb / Flag | Description |
|---|---|
capture | Hit every route in the config and write an observable-behavior snapshot. |
--config <path> | (capture, required) Behavior config JSON: baseUrl plus a routes array of { method, path, body?, headers? }. |
--out <path> | (capture, required) Output path for the snapshot JSON. |
compare | Diff two snapshots and print a human-readable behavior report. |
--json | Machine-readable output for orchestrators (both verbs). |
Per-route errors are recorded rather than fatal, so the snapshot always has an
entry for every route. capture fails operationally if no route returns a real
response (target down), since an all-errored snapshot cannot be meaningfully
diffed.
Exit codes
capture wrote a snapshot with at least one reachable route; compare found every route identical.1: operational error. Unreadable config or snapshot, invalid JSON, cannot write output, or every route was unreachable.2: compare gate fails. One or more routes changed, were added, removed, or are dead in both snapshots.Example
$ adlc behavior-diff capture --config behavior.json --out after.json
captured 4/4 routes (0 errors) → after.json
$ adlc behavior-diff compare before.json after.json
2 routes identical, 1 changed, 0 errored
~ GET /health:
body (json): 1 change:
~ version: "1.0.0" → "2.0.0"
exit 2Go deeper
- packages/behavior-diff
- Why the human gate reviews behavior, not diffs: Two Human Gates.