Source annotations: letting a file declare the decision it lives under (complement to affects)

[aballiet]

First: thank you for making the schema CC0 and saying why in ADR-0006. We took you up on it — our decision corpus is now vendored adrkit v0.1.0 records (9 of them, validating against schema/adr.schema.json), with our own zero-dependency checker on top because our repo can't take dependencies in its tooling directory. Wire-compatible without the coupling, which is exactly what that licence choice enables.

While migrating we hit one gap and want to check whether it's in scope before proposing anything.

The gap

affects[] is the only way a decision reaches a file, and it's declared on the record. That works well when a decision has a small defining surface. It gets expensive when the decision governs a subsystem, because the pattern has to be broad.

Concretely, on a 1,357-file repo, expressing "these decisions govern the sync subsystem" needed directory patterns (src/services/authored-sync/**):

	Directory patterns	Defining files only
Files matched	163 (12%)	28 (2.1%)
Context injected if an agent touches all of them	~56k tokens	~9.1k tokens

We narrowed to the defining files, which fixed the cost — but silently dropped the neighbourhood. Files where the decision is real but ambient (wedge.ts, genesis.ts, a legacy-migration path) ended up with no link at all.

What we did, and the question

We added an inbound direction: a source file declares the decision it lives under, in a comment.

/**
 * @adr 0003 -- this re-seed is what makes a wire-namespace move total. Re-keying works by
 * seeding the NEW namespace from local state; it never translates ops already in the bucket.
 */

affects stays narrow and declarative; anything else opts in with one line, at zero cost until something reads the file. It's e-adr's @ADR(1) idea, and it seems complementary to affects rather than competing with it.

As far as I can tell from the tree there's no source-annotation resolution today — the annotation code under packages/adapters/catalog-backstage is Backstage catalog ownership, a different concept. Please correct me if I've missed it.

Two questions:

1. Is this in scope for adrkit? It's arguably a resolver concern rather than a schema one, but it does change what "which decisions govern this file" means.

2. If yes — inbound edge, or a new affects type? We modelled it as an inbound edge discovered at resolution time, with no schema change, for two reasons: semantically the file is opting in rather than the record declaring it, and it avoids touching the emit-parity gate that CONTRIBUTING flags as a steep on-ramp. But a type: annotation matcher would keep everything declared in one place, which has its own appeal.

ADR-0012 felt like precedent for the general shape — an explicit annotation beating inference for binding entities to paths — but pointed the other way, so I may be over-reading it.

Happy to implement whichever direction you prefer, following the observe-it-failing-first rule in ADR-0016. Wanted to check the design before writing code rather than after.