Resolve reference

Resolve a reference from another tool (UUID, short ID or identifier, optional version) and tell whether the version is current.

Command element.resolve. Reads the workspace and changes no file.

Input

Field	Type	Required	Description
`ref`	`elementRef`	yes	UUID, short ID or identifier (e.g. SR-036), any case; several matches give ref.ambiguous.
`version`	`version`	no	The version the reference stores (D-013); optional. A version of another normal form than the one the tool computes (n1) is refused with input.invalid (ADR-0005).
`versionDate`	`boolean`	no	Also give the date of the current version (`versionDate`, D-013, ADR-0005), read from the Git history, as element.get does with the same input. Without it no git runs and `versionDate` is left out. Default: `false`.
`repository`	`string`	no	Which of the elements ref names is meant: the workspace name of its repository, as details.candidates of ref.ambiguous give it (for example one copy of a file whose UUID another file shares, SR-088; #255). Only the elements ref names count; when none of them lies there, the error is ref.unknown with them as details.candidates.
`file`	`relativePath`	no	Which of the elements ref names is meant: its file, relative to its repository, as details.candidates of ref.ambiguous give it (#255). Give repository too when the same path is in several repositories; when several elements are still left, the error is ref.ambiguous with them.

Output

Field	Type	Required	Description
`element`	`element`	yes	The element as element.get shows it, with title, text, status, current version (SR-060 AK1), verification status per view it is in (SR-031, SR-034, SR-047 AK3) and validation status (SR-038) and, with the input `versionDate`, the date of that version (as element.get gives it; left out without the input). Without a version (a value that counts has no normal form) `version` and `versionDate` are left out and the hints end with a `file.faulty` warning, as in element.get (#276). An unknown reference is the error ref.unknown, one that fits several elements ref.ambiguous with details.candidates (AK3). A short ID whose prefix fits no element stays ref.unknown, never another element; when its tail fits exactly one element of another type, details.candidates names that element and the message asks whether its short ID was meant (prefix may be outdated, #275).
`current`	one of `"current"`, `"outdated"`, `"unknown"`, `null`	yes	Whether the given version is the element’s current version, computed from its file as it is now (SR-060 AK2): “current” or “outdated”; “unknown” when the element has no version to compare with (a value that counts has no normal form, `.inf` or `.nan`, ADR-0005: `element` comes without `version` and with a `file.faulty` warning that says why, #276); null when no version was given. Strings, not booleans, so a caller that tests the field for truth never takes “unknown” for current.

App

In the command prompt (Ctrl+Shift+P, macOS ⌘⇧P): the command Resolve reference.

CLI

reqseq element resolve, with --json for the output as JSON. Its help:

Usage: reqseq element resolve <ref> [options]

Resolve a reference from another tool (UUID, short ID or identifier, optional
version) and tell whether the version is current.

Options:
  --ref <value>           instead of the argument <ref>
  --version <value>       The version the reference stores (D-013); optional. A
                          version of another normal form than the one the tool
                          computes (n1) is refused with input.invalid
                          (ADR-0005).
  --version-date          Also give the date of the current version
                          (`versionDate`, D-013, ADR-0005), read from the Git
                          history, as element.get does with the same input.
                          Without it no git runs and `versionDate` is left out.
                          default: false
  --no-version-date       set version-date to false
  --repository <value>    Which of the elements ref names is meant: the
                          workspace name of its repository, as
                          details.candidates of ref.ambiguous give it (for
                          example one copy of a file whose UUID another file
                          shares, SR-088; #255). Only the elements ref names
                          count; when none of them lies there, the error is
                          ref.unknown with them as details.candidates.
  --file <value>          Which of the elements ref names is meant: its file,
                          relative to its repository, as details.candidates of
                          ref.ambiguous give it (#255). Give repository too when
                          the same path is in several repositories; when several
                          elements are still left, the error is ref.ambiguous
                          with them.
  --input <json|@file|->  command input as JSON: inline, from a file, or from
                          standard input
  --workspace <path>      workspace root (default: nearest folder upwards with
                          reqseq-workspace.yaml)
  --json                  print exactly the command output as JSON
  --yaml                  print the whole command output as YAML, problems one
                          per line
  -h, --help              show help

API

POST /v1/commands/element.resolve on the local API (reqseq serve api), with the input as the JSON body; the answer is the output.

MCP

Tool element_resolve of the MCP server (reqseq mcp), with the input as its arguments.