feat(relationships): add decision code-scope Applies To vocabulary [roadmap:decision-to-code-proximity]

[tcballard]

Summary

Implements Initiative 1 of the decision-to-code-proximity roadmap (epic #273, sub-issue #274), adopting the rac-decision-applies-to-scope requirement. A decision can now declare the code paths or components it governs, and rac relationships --validate existence-checks those declarations against the repository — closing the "which recorded decisions govern the file I'm editing?" gap as corpus data rather than prose.

Adds:

• An optional ## Applies To section on decisions, modelled as a first-class applies_to relationship edge.
• Existence-checking of literal path/directory entries by rac relationships --validate, with a new applies-to-target-not-found issue code.
• Dogfood on the four evidence ADRs, boundary + adjacent-type tests, and user-facing docs.

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/decision-to-code-proximity.md (Initiative 1)

Requirement:

• rac/requirements/rac-decision-applies-to-scope.md (gap 7 of the traceability audit; delivery here closes its decision-scope box on Epic: relationship-vocabulary — close the traceability gaps #236)

Relevant ADRs:

• adr-007 — additive JSON contract (new optional section, new issue code; existing corpora byte-identical)
• adr-018 — RAC directory as canonical root (the .rac/ anchor for path resolution)
• adr-019 — asset references
• adr-065 / adr-066 — declared, never inferred; a pure function of declared references and the file tree
• adr-002 — deterministic, offline (POSIX-normalised, no database)
• adr-034 — reports which decisions bind, never a compliance judgement

Scope

Included

• ## Applies To recognised and extracted on decisions only; additive and append-only; classification-neutral.
• Deterministic slash-or-glob entry classification: a literal path/directory (contains /) is existence-checked; a glob (*/?/[) is recorded as a declared pattern; a component name (no /, no glob) is a recorded label.
• Path resolution anchored to the nearest .rac/ (ADR-018), POSIX-normalised so results are byte-identical across platforms; absolute or repo-escaping entries cannot name an in-repo scope and are reported not-found.
• Surfacing: the scope flows through the existing single-schema consumers (get_related, inspect, rac export --graph) as an external, unresolved, filesystem-scoped edge.
• The four evidence decisions declare checkable scope (adr-018 → rac/, adr-023 → src/rac/, adr-027 → .github/workflows/, adr-033 → src/rac/mcp/).

Excluded

• The path→decisions lookup — the CLI subcommand and the additive path argument on find_decisions, plus the deliberate ADR-030 pinned-description revision. That is rac-path-decisions-lookup / decision-to-code-proximity: path→decisions lookup — CLI subcommand plus additive find_decisions path argument #275, a separate change; find_decisions is byte-identical here to preserve that boundary.
• Glob existence-checking — globs are recorded, not checked; matching semantics belong to the lookup (advisory-first existence-checking is a documented later option).
• Non-decision artifact types declaring code scope — a later phase.
• Explorer surfacing and the freshness drift-gate join — decision-to-code-proximity: downstream joins — Explorer surfacing and the drift-gate handoff #276.
• Component-id registry or resolution semantics — component names stay recorded labels this cycle.
• No scope-coverage enforcement (no "every decision must declare scope" gate).

Product / Architecture Decisions

• First-class edge over a standalone section. ## Applies To is registered in RELATIONSHIP_SECTIONS with an applies_to EdgeSpec, so it auto-surfaces through get_related/inspect/graph — one vocabulary read by every consumer, per the roadmap's "authored once, read everywhere". This keeps the freshness drift gate and Explorer joining on the same reference rather than a parallel one.
• New declarative filesystem_scoped flag on EdgeSpec distinguishes this edge from the format-linted external edges (related_tickets, verified_by). Like them it skips id resolution, range, and status checks; unlike them its literal entries are existence-checked. No existing edge did filesystem checking (even verified_by, whose targets are file paths, is format-linted, never checked), so this is a new resolution mode rather than an extension of one.
• Issue code applies-to-target-not-found, severity error. It fails --validate like the other referential-integrity breakages and is additive to the JSON contract.
• Filesystem-scoped entries do not count toward relationships_checked, consistent with how the external edges are excluded — the metric stays the id-resolution count and is unchanged for existing corpora.
• docs/artifacts.md left unchanged: its optional-section lists deliberately abridge the external-reference family (Related Tickets / Verified By are already omitted and documented in relationships.md), so Applies To is documented alongside them there, not added to the per-type list.

User-Facing Contract

CLI

No new command in this change. rac relationships DIR --validate gains the code-scope check:

## Applies To
- src/rac/
- .github/workflows/
- src/**/*.py      # recorded pattern, matched by the lookup (#275)
- Explorer         # recorded label

A missing literal path is reported; a glob or component name is not.

Human Output

A flagged entry renders under Broken Relationships as ✗ PATH path not found.

JSON Output

rac relationships --validate --json emits the existing issue shape {source_path, relationship, target, code} with code: "applies-to-target-not-found" and relationship: "applies_to". SARIF carries the reason "declared path does not exist in the repository". No existing field changes; find_decisions output is byte-identical.

Exit Codes

• 0: every reference (and declared literal path) resolves.
• 1: one or more validation issues, including a missing ## Applies To path.
• 2: path not found (usage).

Verification

Ran

• rac validate rac/ → PASS — 362 valid, 0 invalid.
• rac relationships rac/ --validate → exit 0, 2049 relationships checked, 0 issues (the four dogfood ADRs' paths all exist).
• rac review rac/ → 95/100, no priority 1–2 findings.
• pytest tests/test_relationship_validation.py tests/test_relationship_graph.py tests/test_schema.py tests/test_schema_agreement.py → 78 passed. Full non-TUI suite: 1616 passed (the two failures — test_explorer_app, test_hook — reproduce on the pristine tree and are environment gaps: an incompatible textual and rac not on PATH).

Covered

• Existing path and directory resolve clean; missing literal path → applies-to-target-not-found (target + source preserved).
• Glob (src/**/*.py) and component name (RAC Core, Explorer) recorded, never flagged.
• Absolute (/etc/passwd) and escaping (../outside/) entries reported not-found rather than followed out of tree.
• ./-prefixed entry normalises and resolves.
• Adjacent-type guard: a requirement declaring ## Applies To is relationship-edge-unsupported, not a scope check; the section never shifts decision classification.
• CLI/JSON/human faces exercised end to end.
• Schema-, edge-registry-, and cross-consumer-agreement pins updated to include the additive member.

Review Path

1. src/rac/core/artifacts.py, src/rac/core/relationship_types.py — the schema section and the applies_to edge (filesystem_scoped).
2. src/rac/services/relationships.py — the classifier, repo-root/POSIX-normalise helpers, and the existence-check pass wired into _validate.
3. src/rac/output/human.py, src/rac/output/sarif.py — rendering for the new code.
4. tests/test_relationship_validation.py (+ the three pin updates) — behaviour coverage.
5. the four evidence ADRs, rac/requirements/rac-decision-applies-to-scope.md, docs/relationships.md — dogfood, status, and docs.

Notes For Reviewer

• adr-018 carried a stray unbalanced code fence at EOF; it is closed in passing as part of appending the section (fences are now balanced).
• rac-decision-applies-to-scope is marked Accepted now its vocabulary, validation, and forward get_related surfacing ship; the querying lookup stays open as rac-path-decisions-lookup (decision-to-code-proximity: path→decisions lookup — CLI subcommand plus additive find_decisions path argument #275).
• Post-merge bookkeeping intentionally not done here (needs the merge to land): tick decision-to-code-proximity: applies-to vocabulary — land the decision code-scope section #274 on Epic: decision-to-code-proximity — decisions at the point of edit #273 and the decision-scope/gap-7 box on Epic: relationship-vocabulary — close the traceability gaps #236.
• CHANGELOG.md untouched — it is organised strictly by shipped release with no "Unreleased" section, so the entry belongs to release time (CalVer, ADR-076).

Implementation Process

Implemented with AI assistance under the roadmap contract; the implementation contract (edge modelling and the slash-or-glob classifier) was ratified, and final scope, review, and acceptance decisions were made by the maintainer.