---
schema_version: 1
id: RAC-KTQ63DY1BDFC
type: requirement
---
# RAC v0.7.2 — Relationship Validation

## Context

v0.7.0 introduced explicit relationship metadata.

v0.7.1 introduced repository-level relationship inspection through:

```bash
rac relationships .
```

At this point, RAC can discover declared relationships across a repository but does not yet validate them.

The next step is to detect whether explicit relationship references resolve to known artifacts.

v0.7.2 introduces deterministic relationship validation.

This release checks explicit references only.

It does not infer missing relationships, recommend new links, generate graph visualizations, or perform semantic analysis.

---

## Problem

As repositories grow, relationship metadata can drift.

Examples:

- A Requirement references a Decision that no longer exists.
- A Roadmap references a Requirement using the wrong identifier.
- A Decision supersedes an ADR that cannot be found.
- A Prompt references an artifact that has been renamed.

Without validation, relationship metadata may appear structured but still be unreliable.

RAC should help users detect broken explicit references while preserving the principle that relationships are manually declared knowledge.

---

## Goals

Extend relationship support to validate explicit relationship references.

Support:

- Repository-level target resolution
- Broken reference detection
- Human-readable validation output
- JSON validation output
- Non-zero exit code when broken relationships are found

while remaining:

- Deterministic
- File-first
- AI-optional
- Read-only
- Based only on explicit relationship sections

---

## Reference Model

v0.7.2 shall resolve references using explicit artifact identifiers.

Supported reference examples:

```text
REQ-001
ADR-004
ROADMAP-Q3
PROMPT-REQUIREMENT-REVIEW
```

The resolver shall operate against discovered artifacts in the inspected repository.

The exact identifier extraction rules shall be deterministic and documented.

---

## Requirements

### REQ-001 — Relationship Validation Command

The system shall support relationship validation.

This may be exposed through:

```bash
rac relationships <directory> --validate
```

or a dedicated command if the implementation chooses a clearer CLI boundary.

The preferred v0.7.2 interface is:

```bash
rac relationships <directory> --validate
```

---

### REQ-002 — Artifact Identifier Discovery

RAC shall discover artifact identifiers for supported artifact types.

Identifier sources may include:

- Filename stem
- Document title
- Explicit ID section or metadata, if supported

The selected identifier strategy shall be deterministic.

---

### REQ-003 — Reference Resolution

RAC shall attempt to resolve relationship references against discovered artifact identifiers.

Example:

```markdown
## Related Decisions

- ADR-004
```

If an artifact with identifier `ADR-004` exists, the reference is considered resolved.

---

### REQ-004 — Broken Reference Detection

RAC shall report relationship references that cannot be resolved.

Example output:

```text
Broken Relationships

requirements/search.md
  Related Decisions:
  ✗ ADR-999 not found
```

---

### REQ-005 — Valid Relationship Summary

When all relationship references resolve successfully, RAC shall report success.

Example:

```text
Relationship Validation

Relationships Checked: 14
Broken Relationships: 0
```

---

### REQ-006 — JSON Output

The system shall support:

```bash
rac relationships <directory> --validate --json
```

and return structured validation results.

Example:

```json
{
  "directory": "rac",
  "recursive": true,
  "relationships_checked": 14,
  "broken_relationships": 1,
  "issues": [
    {
      "source_path": "requirements/search.md",
      "relationship": "related_decisions",
      "target": "ADR-999",
      "code": "relationship-target-not-found"
    }
  ]
}
```

---

### REQ-007 — Exit Codes

Relationship validation shall return:

- `0` when validation completes and all relationship references resolve
- `1` when validation completes and broken relationship references are found
- `2` for usage errors, file access failures, or processing failures

This mirrors validation-style behavior rather than advisory inspection behavior.

---

### REQ-008 — Unknown Artifacts

Unknown artifacts shall not prevent relationship validation.

If Unknown artifacts contain relationship sections, RAC may validate their explicit references.

Unknown artifacts shall not be considered valid targets unless they expose a resolvable identifier through the selected identifier strategy.

---

### REQ-009 — Duplicate Identifier Handling

If multiple artifacts resolve to the same identifier, RAC shall report an ambiguity issue.

Example:

```text
Duplicate artifact identifier: ADR-004
```

Duplicate identifiers shall cause validation to fail.

---

### REQ-010 — Self-Reference Handling

If an artifact references itself, RAC shall report a self-reference issue.

Example:

```text
Self-reference detected: requirements/search.md references REQ-001
```

Self-references shall cause validation to fail unless explicitly allowed by the relationship type.

---

### REQ-011 — No Relationship Inference

RAC shall validate only declared relationships.

It shall not infer missing relationships or suggest additional ones.

---

## Non-Goals

### Relationship Recommendations

Not:

```text
This Requirement should probably relate to ADR-004.
```

No relationship suggestions are generated.

---

### Semantic Matching

Not:

```text
This Roadmap seems related to this Requirement because both mention onboarding.
```

No semantic similarity or AI matching is included.

---

### Graph Visualization

Not:

```bash
rac graph .
```

No visual graph output is included.

---

### Graph Algorithms

Not:

```text
Detect all dependency cycles across roadmap initiatives.
```

General graph analysis is out of scope.

---

### Work Management

Relationship validation shall not introduce:

- Owners
- Assignees
- Priorities
- Due dates
- Sprints
- Workflow states
- Delivery tracking

RAC manages knowledge, not work.

---

## Success Metrics

### Functional

- Broken relationship references are detected.
- Valid relationships pass validation.
- Duplicate identifiers are detected.
- JSON output exposes validation issues.
- Exit codes distinguish success, validation failure, and usage errors.
- No AI services are required.

### Product

Users can trust declared relationship metadata because RAC can verify that referenced artifacts exist.

Repositories can use relationship validation in CI without introducing project-management workflows.

---

## Acceptance Criteria

```bash
rac relationships rac/ --validate
```

checks explicit relationship references.

```bash
rac relationships rac/ --validate
```

returns exit code `0` when all references resolve.

```bash
rac relationships rac/ --validate
```

returns exit code `1` when broken references exist.

```bash
rac relationships rac/ --validate --json
```

returns structured validation issues.

Broken references include:

- source path
- relationship type
- target reference
- issue code

Duplicate identifiers are reported as validation failures.

Self-references are reported as validation failures unless explicitly allowed.

No inferred relationships are generated.

No graph output is generated.

No AI services are required.

No files are modified.

---

## Future Considerations

Future releases may introduce:

- Relationship graph export
- Relationship coverage analysis
- Relationship-aware portfolio health
- Artifact lineage tracking
- Relationship-aware review workflows
- Optional viewer integrations

These should build on deterministic relationship validation without turning RAC into a graph UI, project-management system, or AI inference engine.