Release v2.1.7 — Stable

Release v2.1.7 — Stable

Internal cleanup release. No CLI behavior changes. All emitted strings,
exit codes, and JSON contracts are unchanged from v2.1.6.

Changes (merged via PR #11)

• Extracted all 14 E_* error codes to module-level constants; fixed
  trailing-colon token inconsistency in command_register (F1a, F1b, F1c)
• Fixed hardcoded scripts/reqtrace.py path in command_check fix hint —
  now uses Path(sys.argv[0]).name (F2)
• Removed duplicate registry read on check success path (F3)
• Removed double sort in records_from_occurrences / write_ledger (F4)
• Used keyword arguments in ledger_record_from_json to prevent silent
  field swap on reorder (F5)
• Added two regression tests for .md scanner-skip behavior (F6)
• Reverted out-of-scope sort introduced in command_scan output

Verification

• python -m pytest tests/ -v — 120 passed
• python examples/calibration/run.py — 7 passed, 0 failed
• python scripts/reqtrace.py check --strict — OK
• python scripts/reqtrace.py check --strict --format json — {"status":"ok",...}
• mkdocs build --strict — no warnings

Reqtrace v2.1.5 — Bugfix

Reqtrace v2.1.5 — Bugfix

Release date: 2026-06-25

Summary

v2.1.5 stabilizes the evidence convention. It fixes a set of correctness bugs in the CLI, documents stable JSON contracts, removes artificial self-tracing from the production source, and clarifies how @reqtrace markers relate to explanatory comments.

---

Bug fixes

• check --strict=full no longer reads the registry twice. The registry was parsed once for source-file validation and again for the coverage summary; the second parse discarded any parse errors from the first. Both now use the same parsed result.
• register rejects duplicate handles before writing. Previously a second register call for an existing handle would append a duplicate entry to docs/handle-registry.jsonl. It now emits E_DUPLICATE_HANDLE and exits without writing.
• check reports stale-ledger errors even when the scan also has errors. Previously, a scan error would suppress the E_STALE_LEDGER failure, masking stale-ledger state from callers.
• check --strict=full emits E_REGISTRY_SOURCE_MISSING for path-traversal or OS errors, not only missing files. The error message includes the underlying cause.
• check --strict=full reuses the validated registry for the coverage summary rather than re-reading it from disk, eliminating a TOCTOU window.
• check --strict and check --strict --format json produce consistent exit codes across error, stale-ledger, and OK paths.
• Windows path normalization. Configured paths in .reqtrace.json are now normalized to forward slashes before use, fixing scan mismatches on Windows.
• E_REGISTRY_PARSE_ERROR is now emitted for malformed JSONL lines, non-object records, and invalid handle schemas, giving machine-readable diagnostics for corrupt registry files.

---

New features

• docs/schema.md — stable JSON contracts. Documents the exact field contracts for scan --format json, report --format json, check --format json, docs/trace-ledger.jsonl, and docs/handle-registry.jsonl. Field names and types are stable within a schemaVersion.
• report --format json now includes registered, full, partial, and zero summary counts in the versioned envelope alongside the per-handle arrays.
• check --strict=full validates source field existence. Fires E_REGISTRY_SOURCE_MISSING when a registry entry's source path does not resolve to a real file.
• docs/hierarchy-patterns.md — reference patterns for vertical (parent) and horizontal (links) handle relationships. Reserved fields are preserved through generate; v2.1.5 does not validate hierarchy semantics.

---

Marker semantics and dogfooding policy

• Production source is no longer self-traced. The 15 @reqtrace TRD-* markers in scripts/reqtrace.py are removed. They pointed to handles with no documented requirement text, making the self-tracing circular rather than meaningful.
• "Marker Semantics" policy added to README.md. States explicitly: markers are evidence annotations, not explanatory comments; markers do not replace comments that explain intent, invariants, or security assumptions; existing explanatory comments must be preserved when adding markers.
• AGENTS.md updated with comment-preservation rule. Agents are now instructed to preserve existing explanatory comments when annotating and to flag nontrivial functions that lack explanatory comments.
• skills/reqtrace-annotation/SKILL.md updated. Uses "marker" and "annotation" consistently; no longer calls @reqtrace a "comment." Adds a step prompting the annotator to note when a function needs an explanatory comment alongside the marker.
• examples/refresh-token/ — all three source files now carry both a @reqtrace marker and an explanatory comment, demonstrating correct coexistence.
• examples/calibration/README.md added. States that calibration fixtures are scanner/report/check fixtures, not production annotation style guides.
• docs/reference.md "Self-Tracing" section renamed to "Production Source" and rewritten to state that production code should only carry markers tied to meaningful upstream requirements.

---

Tests

• 118 unit tests pass (tests/), including a new tests/test_examples.py suite that:
  • asserts README declares marker-semantics policy and the no-default-dogfooding rule;
  • asserts AGENTS.md contains the comment-preservation rule;
  • asserts the annotation skill does not call markers "comments";
  • asserts the calibration README declares fixture scope;
  • asserts all examples/refresh-token/src/*.js files carry non-marker comments;
  • asserts scripts/reqtrace.py contains no @reqtrace TRD-* markers.
• All 7 calibration scenarios pass (examples/calibration/run.py).

---

Upgrading from v2.1.0

No breaking changes to CLI interface, ledger format, or registry format. The schemaVersion field in report --format json remains "2.1". Teams consuming the JSON contracts should refer to docs/schema.md for the now-documented stable field set.

If you were relying on the self-tracing markers in scripts/reqtrace.py as coverage evidence, those ledger entries are removed. Run generate after upgrading to resync your ledger.

Reqtrace v2.1 — Verified

---

Reqtrace v2.1 — Verified

Released: 2026-06-21

What's new

Document hierarchy enforcement

A new doc_hierarchy config field lets you declare your document stack (e.g. ["BRD", "ARD", "DRD", "TRD"]). When set, check enforces two rules on implementation annotations:

• E_OFFLEAF_HANDLE — rejects any implementation annotation whose handle prefix is not the leaf document type. Ensures code traces to specs, not to upstream goals or architecture docs.
• E_MULTI_HANDLE_EVIDENCE — rejects consecutive implementation annotations that name more than one handle. Each evidence block must be single-purpose.

Both rules fire regardless of --strict level. Set doc_hierarchy: [] to disable.

Registry source validation

check --strict=full now validates that every registry entry with a source field points to a file that actually exists on disk.

• E_REGISTRY_SOURCE_MISSING — reports the handle and the missing path. Entries with no source field are exempt.

Calibration fixtures

Seven self-contained mini-projects under examples/calibration/ prove every documented claim against the live CLI:

Scenario	Claim
01-full-coverage	Full-bucket classification
02-partial-impl-only	Partial-bucket classification
03-strict-full-vs-ledger	Two strict levels behave differently
04-doc-hierarchy-violation	E_OFFLEAF_HANDLE fires correctly
05-multi-handle-evidence	E_MULTI_HANDLE_EVIDENCE fires correctly
06-scan-diff	scan --diff filters committed annotations
07-legacy-migration	migrate rewrites V1 form; result passes check

Run all scenarios: python examples/calibration/run.py

Bug fixes and hardening

15 edge-case fixes across the CLI (BUG-1 through BUG-15), covered by 30 new tests in tests/test_edge_cases.py.

Registry

87 canonical handle entries updated to point to docs/reference.md. 34 retired V2M-* entries removed. Registry now has 89 valid entries with zero source violations.

Upgrading from v2.0

Add doc_hierarchy to .reqtrace.json to opt into hierarchy enforcement — existing configs without it are unaffected. Run check --strict=full to surface any registry source issues before enabling it.

v1.0

Full Changelog: https://github.com/paragon-ux/Reqtrace/commits/v1.0.0