---
schema_version: 1
id: RAC-KTQ63DXA9ZZJ
type: requirement
---
# RAC v0.7.1 — Relationship Inspection

## Context

v0.7.0 introduced explicit relationship metadata across supported RAC artifact types.

Artifacts can now include structured relationship sections such as:

- Related Requirements
- Related Decisions
- Related Roadmaps
- Related Prompts
- Supersedes

v0.7.0 focused on making relationships explicit and machine-readable within individual artifacts.

The next step is to inspect relationships across a repository.

v0.7.1 introduces repository-level relationship inspection through:

```bash
rac relationships .
```

This release discovers explicit relationships already declared in artifacts.

It does not infer relationships, validate targets, generate graphs, or recommend links.

---

## Problem

Once artifacts can reference each other, users need a way to see those relationships across a repository.

Without repository-level relationship inspection, users must manually open individual files to answer questions such as:

- Which artifacts reference this Decision?
- Which Requirements are linked to this Roadmap?
- Which Prompts are associated with Requirements?
- Which Decisions supersede other Decisions?
- Which artifacts declare relationships at all?

RAC should provide a deterministic, repository-level view of explicit relationships without introducing inference or graph analysis.

---

## Goals

Introduce:

```bash
rac relationships <directory>
```

to inspect explicit relationship metadata across RAC artifacts.

Support:

- Repository-level relationship extraction
- Human-readable relationship summaries
- JSON relationship output
- Per-artifact relationship entries
- Basic relationship counts

while remaining:

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

---

## Requirements

### REQ-001 — Relationships Command

RAC shall support:

```bash
rac relationships <directory>
```

to inspect explicit relationships across a directory or repository.

Directory traversal shall follow the same default behavior as `rac inspect` and `rac stats`.

---

### REQ-002 — Recursive Directory Inspection

Relationship inspection shall inspect Markdown files recursively by default.

The system shall support a top-level-only mode if equivalent behavior exists for repository inspection commands.

Example:

```bash
rac relationships rac/
```

---

### REQ-003 — Relationship Extraction

RAC shall extract explicit relationship metadata from supported artifact types.

Supported relationship fields include:

- Related Requirements
- Related Decisions
- Related Roadmaps
- Related Prompts
- Supersedes

Only explicit relationship sections shall be extracted.

---

### REQ-004 — Relationship Summary

Human-readable output shall include a repository-level summary.

Example:

```text
Relationships

Files Inspected: 24
Artifacts With Relationships: 8
Relationships Found: 14

By Type:
- Related Decisions: 6
- Related Requirements: 4
- Related Roadmaps: 2
- Related Prompts: 1
- Supersedes: 1
```

---

### REQ-005 — Per-Artifact Relationship Output

Human-readable output may include per-artifact relationships.

Example:

```text
requirements/search.md
  Related Decisions:
  - ADR-004

roadmaps/q3-platform.md
  Related Requirements:
  - REQ-001
  - REQ-002
```

---

### REQ-006 — JSON Output

The system shall support:

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

and return structured relationship data.

Example:

```json
{
  "directory": "rac",
  "recursive": true,
  "total_files": 24,
  "artifacts_with_relationships": 8,
  "relationship_count": 14,
  "counts": {
    "related_decisions": 6,
    "related_requirements": 4,
    "related_roadmaps": 2,
    "related_prompts": 1,
    "supersedes": 1
  },
  "artifacts": [
    {
      "path": "requirements/search.md",
      "type": "requirement",
      "relationships": {
        "related_decisions": [
          "ADR-004"
        ]
      }
    }
  ]
}
```

---

### REQ-007 — Unknown Artifacts

Unknown artifacts shall not fail relationship inspection.

If an Unknown artifact contains recognizable relationship sections, RAC may report them as relationship metadata.

Unknown artifacts shall remain classified as Unknown.

---

### REQ-008 — Empty Relationship Repositories

Repositories with no relationship metadata shall produce a successful result.

Example:

```text
Relationships

Files Inspected: 12
Artifacts With Relationships: 0
Relationships Found: 0
```

This shall exit with code `0`.

---

### REQ-009 — File Input

The system may support:

```bash
rac relationships artifact.md
```

for inspecting relationships in a single file.

If implemented, the output shall follow the same model as directory inspection with one artifact.

---

### REQ-010 — Exit Codes

The command shall return:

- `0` when relationship inspection completes successfully
- `2` for usage errors, file access failures, or processing failures

The presence or absence of relationships shall not affect the exit code.

---

## Non-Goals

### Relationship Validation

Not:

```text
ADR-004 exists and is valid.
```

v0.7.1 does not validate whether relationship targets exist.

---

### Broken Link Detection

Not:

```text
Related Decision ADR-999 was not found.
```

Broken-reference detection belongs to v0.7.2 or later.

---

### Graph Generation

Not:

```bash
rac graph .
```

v0.7.1 does not generate graph output or visualizations.

---

### Relationship Inference

Not:

```text
This Requirement probably relates to ADR-004.
```

Only explicit relationship metadata is inspected.

---

### Relationship Recommendations

Not:

```text
Consider linking this Roadmap to REQ-012.
```

No relationship suggestions are generated.

---

### AI Relationship Analysis

No AI services shall be used to identify or infer relationships.

---

### Work Management

Relationship inspection shall not introduce:

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

RAC manages knowledge, not work.

---

## Success Metrics

### Functional

- RAC can inspect explicit relationships across a repository.
- Relationship counts are reported by relationship type.
- Per-artifact relationship data is available in JSON.
- Repositories with no relationships still produce successful output.
- Relationship inspection requires no AI services.

### Product

Users can understand how product knowledge artifacts are explicitly connected without manually opening every file.

Users can begin reviewing relationship coverage before RAC performs relationship validation.

---

## Acceptance Criteria

```bash
rac relationships rac/
```

returns a human-readable relationship summary.

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

returns structured relationship data.

```bash
rac relationships rac/
```

exits `0` when no relationships are found.

Relationship counts include:

- Related Decisions
- Related Requirements
- Related Roadmaps
- Related Prompts
- Supersedes

Per-artifact JSON entries include:

- path
- artifact type
- relationships

Relationship targets are not validated.

No relationship inference is performed.

No AI services are required.

No files are modified.

---

## Future Considerations

Future releases may introduce:

- Broken relationship detection
- Relationship target validation
- Relationship graph export
- Relationship-aware portfolio health
- Relationship coverage analysis
- Viewer integrations that consume relationship JSON

These capabilities should build on explicit relationship inspection without introducing AI inference or work-management concepts.