# Agents

Orientation for coding agents working on this repository.

---

## What this repo is

An NLSpec for `traceable-reqs`, a Rust CLI for requirements tracing. No implementation exists yet — this is the design artifact. The expected agent tasks are:

1. Implement the CLI against `SPEC.md`.
2. Verify an implementation against `SPEC.md` and the `example/` fixture.
3. Refine the spec without scope creep.

---

## Sources of truth

- `SPEC.md` — authoritative behavior.
- `example/expected.json` — golden output for the bundled fixture.

If `SPEC.md` and `README.md` disagree, `SPEC.md` wins.

---

## Implementation language

Rust. Do not propose another language without explicit user direction.

---

## Common pitfalls

- The manifest is **required**. Tags never create requirement IDs.
- Tag grammar is strict: `[stage->REQ-ID]`, no internal spaces. A bracketed token on a scanned line that contains `->` but does not match this exactly is a `parse_error` — do not silently skip it.
- Tags count only **inside comments** for Rust, C, C++, and Python. Markdown scans every physical line, including HTML comments.
- Rust/C/C++ block comments are scanned by physical line, with the `/* ... */` range inclusive of both ends.
- Stage vocabulary (`doc`, `impl`, `unit`, `int`) is fixed in core. Custom stages are an optional capability.
- Finding codes (`missing_stage`, `undeclared_id`, `parse_error`, `manifest_error`, `scan_error`) are stable. Do not invent new codes.
- `requirements[].stages` in JSON output always contains all four stage keys, regardless of which are required.
- Evidence paths in JSON are repository-relative with `/` separators. Line numbers are 1-based.

---

## Validating against the fixture

From the repo root:

```text
cd example
traceable-reqs check --json > actual.json
```

Compare against `example/expected.json` per the rules in `example/README.md`:

- `requirements[]` and `findings[]` are sets — sort before diffing (e.g. `jq -S` plus `sort_by`).
- Only `code`, `requirementId`, `stage`, `path`, and `line` are stable. `message` text is illustrative.

The fixture exercises acceptance examples 1–5. `manifest_error` and `scan_error` are operational; cover them in the implementation's own test harness.

---

## Out of scope

The README's non-goals are binding. In particular, do not add:

- IDE plugins or language servers.
- ReqIF or full OpenFastTrace interchange.
- Anything that replaces GitHub Issues or another planner.

The optional capabilities listed in `SPEC.md` (custom stages, priority gates, include/exclude globs, manifest `version`) are not part of core. Leave them out unless the task asks for them.

---

## Pull requests

- Cite the `SPEC.md` section your change targets.
- Behavior changes should add or update a fixture case under `example/`.
- Changes to finding codes, tag grammar, or JSON schema require a `schemaVersion` discussion in the PR.