Package: graph

isSuppressed returns true if the given check name is in this node'ssuppression set. O(1) via the precomputed map; falls back to thelinear scan only if the set was not built (defensive).

effectiveStatus returns the built-in status value, falling back tomodel.StatusDefault ("approved") when no status attr is declared.

CoverageStates returns the coverage state of every requirement node.

TraceRefs returns the declared trace references of one requirement insource order, each resolved to its target and annotated with the resolvedversion and the authored version pin. References that do not resolve arereturned with Resolved=false so the caller can surface link health.

VersionOf returns the declared version of a requirement, or 0.

VerificationStates returns the verification state of every non-syntheticrequirement. Eligible follows the missing-verdict gate (approved measurewith a verify attribute that is not deferred or rejected), so apresentation denominator matches the check's expectation set.

SetFilter restricts per-requirement checks to the given set of requirementIDs. nil means no filter (check everything — the default); an emptynon-nil set means "the filter matched nothing" — no requirement ischecked. The distinction matters: a --filter expression that matches norequirements must scope the graph to the empty set, not reset tocheck-everything. The graph is always built from the full document treeso trace references to filtered-out requirements still resolve; only theper-req check/report loop is scoped.

SetDisjointAttrs enables the disjoint-attribute check for the namedarray-typed attributes. Empty or nil disables it.

inFilter reports whether a requirement ID is in the active filter set.Returns true when no filter is active (nil filter = check everything).

firstDocID returns the first document-id associated with any of the givendirectory paths, or the first directory path itself if no document-idis declared.

inferBoundaries returns two maps describing the V-model topology:rootDirs: directories that are at the top (have no upstream sources, or are declared external).leafDirs: directories that are at the bottom (are not referenced as upstream sources by any other document).

The returned maps are pure functions of the documents; callers shouldtreat them as read-only.

resolveCoverageSource resolves a coverage-expectation token (a document-id or alevel name) to the set of directory paths that satisfy it. Returnsnil/empty when nothing matches.

CheckResults runs all Pass 2 validation checks and returns the combined results.Checks performed:Broken reference (WARNING): trace target not found; also includes duplicate ID and ambiguous reference errors collected during edge creation.Circular dependency (ERROR): cycles detected via DFS.Requires-trace-from coverage (WARNING): for each requirement that declares requires-trace-from, verifies that at least one requirement from each expected source (document-id or level) traces to it.Generic untraced / no-downstream (WARNING) — fallback for requirements that do NOT declare requires-trace-from: the boundary inference still applies so a single requirement stays clean when its document is at the top or bottom of the V-model.Disposition without reason (WARNING).Mandatory disposition (ERROR).Version pin (ERROR): outdated (V > N) and predated (V < N) version pins on trace references. Suppress per-node with reqmd-suppress: [version-pin]. Code: "version-pin", Direction: "outdated" or "predated".ID prefix (ERROR).

checkCircular detects cycles using DFS on the in-memory cached nodes.Returns ERROR results when a cycle is detected.

ensureBoundaries computes the V-model boundaries when CheckResults has notrun yet, so analysis callers get the same boundary inference.

coverageState classifies one node using the coverage rules ofcheckRequiresTraceFromCoverage. It is the single implementation both thecheck and CoverageStates read.

explicitCoverage classifies a requirement that declares (or inherits) arequires-trace-from expectation.

inboundFrom reports whether an in-filter, approved inbound requirement comesfrom one of the expected document directories. drafts counts in-filterinbound requirements ignored by the status gate.

genericCoverage applies the boundary-aware untraced rule for requirementswithout a requires-trace-from expectation: an inbound link, the rootboundary, or a nested sub-requirement needs no coverage.

checkRequiresTraceFromCoverage runs two related checks:For each requirement that explicitly declares requires-trace-from (even requires-trace-from: []), verify that at least one inbound edge originates from each expected document-id or level. Unknown expectations produce a WARNING.For requirements that do NOT declare requires-trace-from, fall back to the generic untraced / no-downstream checks using the V-model boundary inference so a top-level or bottom-level document stays clean.

hasFilteredInbound reports whether any inbound edge originates from arequirement in the active filter set. With no filter active (nil), itdegenerates to "has any inbound" — preserving the pre-filter behaviorexactly without iterating the inbound list.

hasFilteredOutbound reports whether any outbound edge targets arequirement in the active filter set. With no filter active (nil), itdegenerates to "has any outbound" — preserving the pre-filter behavior.

checkDispositionReason detects nodes where disposition is set to a valueother than "implemented" but disposition-reason is missing or empty.Returns WARNING for each.

checkMandatoryDisposition detects nodes in directories wheremandatory-disposition is set and the requirement has no disposition value.Returns ERROR for each violation.

checkIDPrefixes validates that every requirement ID matches the declaredprefix for its document directory and that no two directories share a prefix.Prefix collision is an ERROR: two document directories must not declare thesame ID prefix, since that would make requirement IDs ambiguous across docs.

pinStatus classifies a single version pin against its target'scurrent version. Shared by checkVersionPins (which emits findings)and RepinDeltas (which proposes edits). Returns the direction("outdated", "predated", or "" for current) and ok=true when thepin is comparable to the target. Returns ok=false when the pinshould be skipped (target missing, external, unversioned, orthe node suppresses the version-pin check).

checkVersionPins compares each downstream requirement's ~N version pinon a trace reference against the upstream requirement's version.Findings:outdated — upstream version V > pinned N. Downstream must be re-verified.predated — upstream version V < pinned N. Downstream claims a version that does not exist on the upstream; data integrity issue.

Both emit ERROR by default. Outdated findings carryCode="version-pin" + Direction="outdated" and can be demoted to WARNINGby the cmd layer when --relaxed-versions is set. Predated stays ERROR.

Skip rules are shared with RepinDeltas via pinStatus.

measureGate applies the shared eligibility gate for the outcome-gatedchecks: a node must be a measure (not a result), an approved coverageprovider (draft measures are not expected to have results), and notdeferred/rejected (those are exempt from verification).

checkMissingVerdict flags approved verification measures whose rolled-upevidence set is empty. A measure is any approved, non-result node carryinga verify attribute (see isMeasure). Evidence is the union of themeasure's own attached results and the results of approved, in-filternodes in its inbound trace closure (downstream test cases). Draft measuresare skipped (a draft measure is not expected to have results yet).

The check runs only when result pseudo-requirements are present in thegraph (loaded via check --results). With no results loaded, no nodehas IsResult=true and the check is a no-op.

Severity: WARNING. Suppress per-node withreqmd-suppress: [missing-verdict]. Code: "missing-verdict".

checkFailingVerdict flags approved measures whose rolled-up verdict isfail. Like checkMissingVerdict it is a no-op when no result nodes arepresent. Draft measures are skipped (a draft measure is not expected togate on results), mirroring the missing-verdict draft gate.

The message names the failing case(s) and their source file(s).

Severity: ERROR. Suppress per-node withreqmd-suppress: [failing-verdict]. Code: "failing-verdict".

hasResultNodes reports whether any synthesized result pseudo-requirementis present in the graph.

isMeasure reports whether a node is a verification measure — arequirement authored with a verify attribute (e.g. verify: Test,verify: Review). Whether a result currently traces to it is irrelevant tothe definition (see checkMissingVerdict). Result nodes are not measures.

evidenceItem derives an EvidenceItem from a synthesized result node.

evidenceCase resolves the case key of a result node: the #case suffix ona case-keyed result, or the case key of the synthesized test case theresult traces to, or "" for a direct (uncased) result.

measureEvidence gathers the evidence set of a requirement: its ownattached results plus the results of approved, in-filter nodes in itsinbound trace closure (downstream authored test cases and synthesizedcases). Draft in-filter intermediaries are not contributors and arereported in the returned draft count. self holds the results attacheddirectly to the requirement; items is the deduplicated union (by casekey, keeping the higher severity).

failingEvidence returns the evidence items whose outcome is fail.

severityOf computes the rolled-up severity of a node's evidence set,recursing through approved, in-filter intermediaries. Results are cachedon the graph (invalidated by SetFilter) so a whole check pass stays cheap.

measureSeverity returns the rolled-up severity of a measure's evidenceset (sevNone when the set is empty).

latestOutcomeFor returns the outcome and source file of the result nodetracing to the given measure. Since the result layer(internal/verify.MergeLatest) already collapses to one result permeasure, there is at most one result node per measure. Returns("", "", false) if no result traces to the measure.

checkVerdicts emits an INFO-level result for each measure that has anon-empty rolled-up evidence set, showing the rolled-up outcome. Thismakes passing verdicts visible in the output — without it, a clean runwith --results looks identical to a run without --results. Measureswithout evidence are covered by checkMissingVerdict and emit no verdictline here.

Severity: INFO (never affects exit code). Code: "verdict".

MeasureOutcome returns the latest verification outcome for a measure(pass, fail, skipped, inconclusive) and whether a result exists. Returns("", false) if the measure has no result or is not a measure.

rollupVerdict computes the strict verdict roll-up for a node from itsevidence set: the highest-severity outcome plus a representative sourcefile (the node's own attached result when present, else the file of thehighest-severity downstream item). ok is false when the evidence set isempty. Shared by checkVerdicts and MeasureVerdicts so the roll-up rulelives in one place.

MeasureVerdicts returns, for every non-synthetic node with a non-emptyrolled-up evidence set, the rolled-up outcome, a representative sourcefile, and the deduplicated evidence items. The set is keyed by requirementID and computed from graph adjacency, so a single source of truth feedsall outputs. Returns nil when no results are loaded.

HasResults reports whether the graph contains any synthesized resultpseudo-requirements (i.e. --results was supplied).

RootDirs returns the document directory paths at the top of the V-model(no upstream sources declared, or external), sorted. Uses the cachedboundaries from CheckResults; returns empty if CheckResults has not beencalled.

LeafDirs returns a sorted slice of document directory paths that are atthe bottom of the V-model (not referenced as upstream sources by anyother document).Uses the cached boundaries from CheckResults; returns empty if CheckResultshas not been called.

---

UpstreamNeighbors returns the requirement IDs that the given requirementtraces TO — its parents/upstream requirements. Returns nil if not found.

DownstreamNeighbors returns the requirement IDs that trace TO the givenrequirement — its children/downstream requirements. Returns nil if not found.

ResolveTraceRef resolves a raw trace reference (as written in thetrace attribute, before pin stripping) to the bare requirement ID itpoints at, using the same rules New uses: a doc-id/ID prefix resolvesthrough document-ids, falling back to a directory path; a bare IDresolves globally. ok is false for a dangling or ambiguous-everywherereference. Callers that need dangling refs keep the raw string.

Documents returns the document slice the graph was built from, in theorder given to New. Exports and reporters use it to look up authoredmetadata (attributes, titles) that the cached node view does not carry.

RepinDeltas computes the list of version-pin changes the repincommand would propose (or apply) against this graph.

Without promoteUnpinned, only outdated findings are returned —refs whose pin is strictly below the upstream's current version.Predated findings (pin strictly above upstream version) aresurfaced separately so the user can see them; repin neverauto-fixes a predated pin because it is a data integrity error,not a process error.

With promoteUnpinned=true, refs that have no pin at all(~N not present in the source) against a versioned upstreamalso produce a delta. This converts "no claim" into "claimed atcurrent version" — the caller is expected to opt in deliberately.

Rules shared with checkVersionPins:Skip synthetic nodes (result pseudo-requirements and future synthesized test cases — they exist in memory only, so there is no source file to rewrite). IsResult is kept for nodes built directly in tests that predate the Synthetic document marker.Skip nodes that suppress the version-pin check.Skip refs whose target is external (versions out of our control).Skip refs whose target has no version (no ground truth).

Returns deltas sorted for stable output: by source file, thenrequirement ID, then source ref.

isCoverageProvider reports whether a node counts as a valid upstreamcoverage source for downstream requirements. A node is a coverageprovider when its document has opted out of the status lifecycle(x-reqmd.ignore-status) or its effective status is "approved".

checkDisjointAttribute verifies that for every trace link, the source andtarget requirements have at least one overlapping value for each declareddisjoint-check attribute. Requirements with an empty/absent value for theattribute are exempt ("applies to all"). Both non-empty with zerointersection → ERROR. Filter-aware: only checks source reqs in the activefilter set.