markharness

0043: Make traceability working-tree only and drop the --format option

Status

Accepted (decided 2026-10-06). Replaces 0033’s “--at is optional, and omitting it reads the working tree” (the decision to read the working tree itself still stands).

Background

0033 kept --at <ref> on traceability and made omitting it read the working tree. No one has used --at <ref> since. The GUI reads only the working tree, and reads a specific committed point through coverage --at. The only use of --at left in the design doc is one line, “to check committed state”.

Keeping --at costs:

Also, coverage, impact, traceability, import and release scope show each have --format, but its only value is json, so there is nothing to choose. It states only that the output is always JSON, and no human-readable output is planned (--json on generate/verify switches to human text, which is a different meaning).

Decision

1. Remove --at from traceability and traceability show

Both commands read the working tree only. To read a specific committed point, use coverage --at.

The output’s at is removed too. With the working tree as the only source its value is always "working-tree" and carries no information (the purpose in 0033 decision 2, telling the sources apart, is no longer needed). When traceability show --uid finds nothing, the error names only the uid.

impact and coverage keep --base/--head and --at, since comparing two points and auditing a release are their purpose (as in 0033 decision 4).

2. Remove --format from coverage, impact, traceability, import and release scope show

The output is always JSON. When human-readable output is needed, an option of the needed shape is added at that point.

Consequences

Alternatives considered and rejected