ADR-018: Cross-graph references are advisory unless the consumer grants authority
Example from HELIX’s own docs. This generated page comes from
docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.
Source identity (from
02-design/adr/ADR-018-advisory-vs-governing-authority.md):
ddx:
id: ADR-018
authoring:
home: repo
status: accepted
depends_on:
- ADR-017
- ADR-004
- ADR-013ADR-018: Cross-graph references are advisory unless the consumer grants authority
| Date | Status | Deciders | Related | Confidence |
|---|---|---|---|---|
| 2026-11-06 | Accepted | HELIX maintainers | ddx.links, external_edges, concerns, SD-003 | Medium |
Problem
A general technology assessment may inform a client’s ADR without overruling
client requirements or approved decisions. Today authority is implicit and
positional within one flow, external_edges is always empty, and ddx.links
is used by the skill and modes but undefined in artifact-schema.md. Atlas
needs typed relationships and an explicit informational/governing split.
Decision
- Extend the existing
ddx.linksentry shape{id, kind}(as inkind: informed_by) with optionalauthorityandrev:{id, kind, authority?, rev?}.kindreads from this document to the target. - Reuse existing predicates first:
depends_on,informs,supersedes. Addkindvaluesaddresses,evaluates,supported_by,contradicts(alongside the existinginformed_byandinforms) only as link kinds, not new top-level fields.revpins the target revision read. - Within a flow, positional authority is unchanged.
- A link that crosses a flow or Atlas boundary is advisory by default.
governingis granted only by the consuming graph’s own marker or profile, never by the referenced graph. contradictsis informational: reported by alignment, never a validation failure.- The concern registry is not generalized. Assessments reference concerns via
addresses; they are not concerns. - External knowledge is referenced as
{graph, id, version}. HELIX defines the shape; DDx or another runtime resolves it. Repository cloning is not required.
Why we chose this
It adds one genuinely new semantic (authority class) plus one link kind
(contradicts), keeps edge vocabulary inside an existing frontmatter key, and
puts the grant of authority on the side that bears the consequence.
Alternatives
| Option | Evaluation |
|---|---|
| Six new top-level predicates | Rejected: most map onto typed links or depends_on. |
| Referenced graph declares its own authority | Rejected: lets external knowledge overrule client decisions. |
| Universal knowledge/entity registry | Rejected: ontology creep; contradicts the concern-registry boundary. |
Consequences
| Type | Impact |
|---|---|
| Positive | Reuse of an Atlas assessment cannot silently override a client ADR. |
| Negative | ddx.links must be specified, and check/align must learn authority. |
| Neutral | Existing ddx.links usage stays valid: a bare id string and {id, kind: informed_by} both mean an upstream reference. |
Open question
Resolved. ddx.links is not defined in artifact-schema.md, but it is in use
in two shapes: bare id strings (docs/helix/02-design/design-desired-state-authoring.md)
and {id, kind: informed_by} mappings (every deliverable). Item 1 extends
that mapping shape rather than introducing another. An earlier draft of this
ADR proposed {rel, target}; that was corrected to match existing usage.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifacts/adr/ADR-018-advisory-vs-governing-authority.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:2fe17f83…d2f7fb1b
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifacts/adr/ADR-018-advisory-vs-governing-authority/",
"digest": {
"alg": "sha256",
"value": "2fe17f83388b09033d0f4972af4cc2f5c8a818071e37c3c9afbf8eccd2f7fb1b"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "z7WVzZD9YseUn28W0fbL5NgpE9YjfwApXA5AZFwS2UqaiClgynfX5Yi7uB7eJd_4Dqt9CPnUeOm6-41FrrqjBQ",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}