# AGENTS.md

Guidance for AI coding agents working **in this repository** (the public,
Apache-2.0 Vibgrate CLI). Humans: see [CONTRIBUTING.md](./CONTRIBUTING.md) and
[ARCHITECTURE.md](./ARCHITECTURE.md).

## Build, test, and check

```bash
pnpm install
pnpm build       # bundles grammars, then tsup
pnpm test        # vitest
pnpm lint        # eslint
pnpm typecheck   # tsc --noEmit
pnpm dev <args>  # run the CLI from source (tsx src/cli.ts)
```

A change is not done until `pnpm test`, `pnpm lint`, and `pnpm typecheck` all
pass.

## Prefer `vg` over grepping

This repo *is* the code-graph tool — use it on itself. Instead of blindly
grepping or reading whole files, build the graph and query it. It is faster and
costs fewer tokens:

```bash
pnpm dev build .
pnpm dev ask "where is the worker pool created?"
pnpm dev show <symbol>      # a symbol and its relations
pnpm dev impact <symbol>    # what breaks if I change this
pnpm dev path A B           # how two symbols connect
pnpm dev tree               # module/area overview
```

Use grep only for things the graph does not model (config files, comments,
strings).

## Determinism rules (non-negotiable)

Identical input must produce identical output (`graph.json`, reports). When
editing anything that reaches serialized output:

- Derive IDs from content (`src/engine/hash.ts`, `ids.ts`) — never from order,
  memory address, or time.
- Sort before serializing; never emit raw `Map`/`Set` iteration order.
- No `Date.now()`, no unseeded randomness (use `src/engine/rng.ts`), no reliance
  on filesystem enumeration order.
- Add or update a test asserting stable output for any graph-affecting change.

## Public-only rule

This is the open, Apache-2.0 distribution. Do **not** add references to private
or internal Vibgrate systems, packages, or proprietary concepts (e.g. any
internal specification format, an `extract` command, or commercial-only
internals). Keep all code, docs, and comments scoped to the public CLI:
deterministic code graph, local MCP server, drift reporting, version-correct
library docs, and agent install. If a feature would require a non-public package,
stop and leave it out.

## Conventions

- Commit with Conventional Commits (`feat:`/`fix:`/`docs:`/`chore:`) and a DCO
  sign-off (`git commit -s`).
- Use `vg` (not `vibgrate`) in docs and examples; both run the same binary.
- Node >= 24, pnpm workspace. (We stay current on the runtime for the same
  reason we gate dependency drift — see below.)

## Dependency-drift gate (dogfooding)

Reducing dependency drift is the product, so this package must be an exemplar of
it. Before the CLI is published, `scripts/check-drift-gate.mjs` runs the
just-built `vg` against this package itself and blocks the release if our own
hygiene regresses:

- **standards** — no banned/abandoned dependency (`vibgrate.standards.json`) is
  in use. Offline + deterministic; also runs on every PR.
- **currency** — no direct dependency is a whole major behind latest, bar
  reviewed allowances. Online (publish) only.
- **budget** — the blended DriftScore stays within `driftBudget`. Online only.

Policy lives in the reviewed `drift-gate.config.json` + `vibgrate.standards.json`.
Loosening a threshold or adding an `allow` entry is a deliberate, reviewed change
(GUARDRAILS §7) — record *why* in the config, never weaken the gate to get a
release out. The gate runs at publish (`publish-cli.yml`, hard) and on every PR
(`ci.yml` `cli-public` job: offline blocking + online advisory). It exits 2
(`GATE_FAILED`) on breach; its logic is unit-tested in `test/drift-gate.test.ts`.