A reference may name a document before its URL resolves

ADR-017: A reference may name a document before its URL resolves

Status Active · Filed 2026-08-03

Context

ADR-016 removed clone-based discovery, and in the same move removed the SG remote — leaving the ancestor’s decisions named only in prose, “eight of them, deliberately not enumerated”. That was one step too far.

This package cites strata-g constantly, and those citations carry real information: which project, which decision. A paragraph saying “eight ancestor decisions, unnamed” preserves none of it. The reason they were dropped was that their URLs don’t resolve — strata-g’s filenames still carry title slugs, so …/docs/decisions/ADR-032.md is a 404.

But that is a statement about today’s filenames, and the plan of record is to port strata-g’s memory to Luria once this package stabilises — at which point ADR-013 applies and that exact URL becomes correct.

Decision

Register SG and keep the citations, accepting that its URLs land later.

A reference has two halves, and they fail independently:

half	SG-ADR-032	when it breaks
the name — which project, which document	durable	never; a code is stable by construction
the URL — where to read it	derived	until the remote adopts the convention

Dropping the citation to avoid a broken URL throws away the durable half to protect the derived one. The prefix is what makes the name sayable at all: an unprefixed ADR-032 in this repo reads as a claim about this project’s thirty-second decision, which does not exist.

So SG is registered on the code-only default, and its links are correct and early rather than wrong. Nothing special-cases it — that is the same construction LU uses, and it is why porting strata-g fixes every one of these links at once with no edit here.

Two remotes, and their difference is the point. LU is public and already on the convention, so luria remotes --check verifies it against the live repository. SG is private, so the same command reports it as unverifiable and will keep doing so until the port. One remote demonstrates the mechanism working; the other demonstrates what it honestly says when it can’t confirm.

Alternatives considered

• A hand-authored lockfile for the eight cited codes. Makes the links work today, and creates a hand-maintained projection of a directory listing with no guard on it — the repository is private, so --check cannot even tell you when it drifts. That is fail-stale, which DP-3 rules out, in exchange for a link that becomes redundant at the port.
• De-prefix back to prose (“one decision in the ancestor project”), as ADR-016 left it. Costs the name as well as the URL, and the name was the part worth keeping.
• A url template for SG. No template can express a title slug, which is what ADR-014 established and remains true.
• Port strata-g first. The right end state and the wrong ordering: Luria is still moving, and porting a 188-document record onto conventions that are still settling would mean porting it twice.
• Suppress the citations with unresolved-ok. They do resolve — to a URL that isn’t populated yet. Using the “names nothing” acknowledgement for “names something not yet published” would blunt the one signal that annotation carries.

Consequences

• ADR-016’s consequence “the ancestor’s decisions are no longer cited by code anywhere” is no longer true. Its body stands as written — that is what a record is for — and this decision is where a reader learns the state changed back.
• Eight links in ADR-009, plus a handful elsewhere, currently 404. That is a stated, dated, reversible condition rather than an oversight, and luria remotes --check will report the whole set flipping to ok in one run when the port lands. That run is the acceptance test for the port.
• Anyone adopting Luria alongside a record that hasn’t been converted gets the same deal, which is the general case this makes explicit: cite it now, and the links improve when the remote does.