---
name: traceable-exit-2-is-an-unparseable-registry
description: "traceable-reqs check exit 2 = the registry did not PARSE (manifest error), not a coverage miss — every coverage reading taken since the bad edit was vacuous, and a real double quote inside a REQ title is the way to cause it"
metadata: 
  node_type: memory
  type: feedback
  originSessionId: a4c12adc-aeca-46be-8433-9a2ac2e20d5e
  modified: 2026-08-25T13:37:56.701Z
---

`traceable-reqs check` has **two failing exits and they mean opposite things.** Exit `1` is a
coverage miss (a REQ lacks evidence for a required stage — the verdict you expect). Exit `2` is a
**manifest error: `traceable-reqs.toml` did not parse at all.** Nothing was checked, so the run
carries no information about coverage, and any "green" you remember from before the bad edit is
the last reading of a *different* file.

Measured 2026-08-25, FIELD-SEAL W4: my newly appended REQ title quoted a doc excerpt with real
double quotes — `("Never pass ... here")` — inside a TOML **basic string**. TOML ends the string
at that quote, so the parse died at that column and the registry had been invalid **from the
moment I appended it**. Everything I had done in between was against an unparseable registry.

**Why this is easy to miss:** the failing REQ ids still appear in your grep of the file, the file
still looks right in an editor, and the batteries around it (build, clippy, tests) are all green
because nothing else reads that file. Only the exit CODE separates "your requirement is
uncovered" from "your requirement does not exist as far as the tool is concerned".

**Do:**
- Read the exit code, not just "treqs failed" — `1` and `2` send you to different places.
- After ANY hand-edit of `traceable-reqs.toml`, run `check` immediately; do not let other work
  ride on top of an unverified registry edit.
- Keep REQ titles free of raw `"` — use backticks, `--`, or single quotes for quoted material.
  The house titles are long prose in basic strings, so this trap is one paste away at all times.
- If you appended a block, assert each new `title = "..."` line starts and ends with a quote and
  contains none in between; that check is three lines of python and catches it before the gate.

Kin: [[traceable-check-cannot-verify-tag-placement]] (green means coverage satisfied, not tags
correct) and [[dont-take-a-diagnosis-as-measured]] — "treqs is red" is a diagnosis, the exit code
is the measurement.

2026-09-08 face (hertz, W3 drift riders) — THE OTHER WAY A treqs 0 IS WEAKER THAN IT SOUNDS.
Exit 2 means nothing was checked. Exit **0** means the tags are PRESENT — it does not mean the code
carrying them COMPILES. I ran `traceable-reqs check` at a composed head, got exit 0 with
`REQ-DOCS-CHANGELOG-PAGE  required: [doc, impl, unit]  stages: +doc +impl +unit -int`, and reported
that twice as a check. Minutes later clippy at the same head exited 101: `error[E0432]: unresolved
imports super::gen_changelog, super::PUBLISHED_DOC_PATHS` — the test module holding all five
`[unit->…]` tags did not build. treqs had read `+unit` green over a test target that does not
compile, because it scans TEXT for tag comments and a comment in a non-compiling file is still a
comment.

**The trap is that I had just ACTIVATED that stage on that reading**, in the same commit, per the
correct rule that a stage activates with the change satisfying it. So the activation and its only
evidence were both certified by an instrument that cannot see whether the evidence is real code.
General: treqs answers "is there a tag saying this is covered", never "does the covering code
build, run, or pass". Sequence a build (clippy `--all-targets`, or the test compile) BEFORE
treating a coverage green as evidence, and never activate a stage on a treqs 0 alone. Kin:
[[a-source-read-cannot-witness-an-integration-cell]] (an instrument blind by construction to the
class it is invoked for) and the standing rule that a tool whose success path has never been made
to fail on purpose is untested.