Skip to content

Reqtrace v2.1.5 — Bugfix

Pre-release
Pre-release

Choose a tag to compare

View all tags
@paragon-ux paragon-ux released this 25 Jun 08:13
· 17 commits to main since this release
v2.1.5
795c054
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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.

Assets 2
Loading