---
schema_version: 1
id: RAC-KTQ63DX66KDG
type: requirement
---
# RAC v0.7.0 — Relationship Metadata

## Context

RAC now supports multiple first-class artifact types:

* Requirements
* Decisions
* Roadmaps
* Prompts

Earlier releases focused on helping users:

* Validate individual artifacts
* Inspect artifact types
* Improve missing structure
* Generate schema-based templates
* Analyze repository composition

The next step is to introduce a consistent way for artifacts to reference each other.

This release does not introduce full relationship analysis, graph generation, or broken-link validation.

Instead, v0.7.0 defines the relationship metadata model that future releases can build on.

This keeps the progression clear:

```text
v0.5.x  Schema-guided authoring
v0.6.x  Artifact vocabulary expansion
v0.7.x  Cross-artifact relationships
```

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

---

## Problem

Product knowledge rarely exists in isolation.

A Requirement may depend on a Decision.

A Roadmap may relate to Requirements.

A Prompt may be used to review or generate Requirements.

A Decision may supersede another Decision.

Today, these relationships are usually captured informally through prose, links, or not captured at all.

This makes it difficult to answer questions such as:

* Which Decisions affect this Requirement?
* Which Requirements support this Roadmap?
* Which Prompt is used to review this artifact?
* Which Decision replaced this older Decision?

Before RAC can analyze relationships, it needs a consistent relationship metadata model.

---

## Goals

Introduce explicit relationship sections and reference conventions across supported artifact types.

Support:

* Relationship sections in artifact schemas
* Consistent reference formats
* Relationship metadata in `rac schema`
* Relationship-aware templates
* Relationship metadata extraction during inspection

while remaining:

* File-first
* Markdown-first
* Deterministic
* AI-optional
* Viewer-agnostic
* Focused on knowledge, not work management

---

## Relationship Model

Relationships are represented as explicit Markdown sections.

Examples:

```markdown
## Related Decisions

- ADR-004
- ADR-012
```

```markdown
## Related Requirements

- REQ-001
- REQ-014
```

```markdown
## Related Roadmaps

- ROADMAP-Q3-PLATFORM
```

```markdown
## Related Prompts

- PROMPT-REQUIREMENT-REVIEW
```

```markdown
## Supersedes

ADR-003
```

v0.7.0 treats these references as metadata only.

The system may extract and display them, but it does not validate whether the referenced artifacts exist.

---

## Requirements

### REQ-001 — Relationship Sections

RAC shall define standard relationship sections for supported artifact types.

Supported relationship sections include:

* Related Requirements
* Related Decisions
* Related Roadmaps
* Related Prompts
* Supersedes

---

### REQ-002 — Relationship Sections in Artifact Specs

Relationship sections shall be represented in `ArtifactSpec`.

They shall be optional unless an artifact type explicitly requires them.

Relationship sections shall not count as missing recommended sections unless explicitly included in that artifact schema.

---

### REQ-003 — Requirement Relationship Metadata

Requirement artifacts may include:

* Related Decisions
* Related Roadmaps
* Related Prompts

Example:

```markdown
## Related Decisions

- ADR-012
```

---

### REQ-004 — Decision Relationship Metadata

Decision artifacts may include:

* Supersedes
* Related Requirements
* Related Roadmaps

Example:

```markdown
## Supersedes

ADR-004
```

---

### REQ-005 — Roadmap Relationship Metadata

Roadmap artifacts may include:

* Related Requirements
* Related Decisions
* Related Prompts

Example:

```markdown
## Related Requirements

- REQ-001
- REQ-002
```

---

### REQ-006 — Prompt Relationship Metadata

Prompt artifacts may include:

* Related Requirements
* Related Decisions
* Related Roadmaps

Example:

```markdown
## Related Requirements

- REQ-001
```

---

### REQ-007 — Schema Reference Support

`rac schema <artifact>` shall include relationship sections where supported.

Example:

```bash
rac schema requirement
```

Output shall include optional relationship sections such as:

* Related Decisions
* Related Roadmaps
* Related Prompts

---

### REQ-008 — Template Support

`rac schema <artifact> --template` shall include optional relationship sections only where appropriate.

Default templates may omit relationship sections unless the artifact type already includes them as expected sections.

If relationship sections are included, they shall use structurally valid placeholder examples.

Example:

```markdown
## Related Decisions

- ADR-001
```

---

### REQ-009 — Inspection Metadata Extraction

`rac inspect <file>` shall extract relationship metadata when present.

Example:

```bash
rac inspect requirement.md
```

Human output may include:

```text
Related Decisions:
- ADR-012
```

JSON output shall include relationship metadata in an additive field.

Example:

```json
{
  "type": "requirement",
  "confidence": 1.0,
  "present_sections": [
    "problem",
    "requirements",
    "related_decisions"
  ],
  "missing_sections": [],
  "relationships": {
    "related_decisions": [
      "ADR-012"
    ]
  }
}
```

---

### REQ-010 — JSON Contract

Relationship metadata shall be exposed as an additive JSON field.

The field shall be named:

```json
"relationships"
```

Relationship keys shall use snake_case.

Relationship values shall be arrays of strings.

Example:

```json
{
  "relationships": {
    "related_decisions": [
      "ADR-004",
      "ADR-012"
    ],
    "related_roadmaps": [
      "ROADMAP-Q3"
    ]
  }
}
```

---

### REQ-011 — Repository Statistics

`rac stats` may include basic relationship-section presence counts.

Example:

```text
Relationships

Artifacts with Related Decisions: 6
Artifacts with Related Requirements: 4
Artifacts with Supersedes: 2
```

v0.7.0 shall not attempt to resolve or validate these relationships.

---

### REQ-012 — Backwards Compatibility

Existing artifacts without relationship sections shall remain valid.

Relationship metadata is optional.

No existing Requirement, Decision, Roadmap, or Prompt artifact shall become invalid solely because it lacks relationship sections.

---

## Non-Goals

### Relationship Resolution

Not:

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

v0.7.0 does not check whether referenced artifacts exist.

---

### Broken Link Detection

Not:

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

Broken-reference detection belongs to a later release.

---

### Graph Generation

Not:

```bash
rac graph .
```

No relationship graph or graph output is included.

---

### Relationship Inference

Not:

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

RAC shall not infer relationships using AI or semantic matching.

Only explicit relationship sections are recognized.

---

### Relationship Recommendations

Not:

```text
Consider linking this Requirement to ADR-012.
```

No suggested links are generated.

---

### Work Management

Relationship metadata shall not introduce:

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

RAC manages knowledge, not work.

---

## Success Metrics

### Functional

* Relationship sections are represented consistently in artifact schemas.
* Relationship metadata can be extracted from supported artifacts.
* Relationship metadata appears in inspection JSON.
* Existing artifacts without relationships remain valid.
* Relationship metadata does not require AI or external services.

### Product

Users can explicitly connect product knowledge artifacts using consistent Markdown sections.

Future relationship analysis can build on a stable metadata model rather than parsing arbitrary prose.

---

## Acceptance Criteria

```bash
rac schema requirement
```

shows supported relationship sections for Requirement artifacts.

```bash
rac schema decision
```

shows supported relationship sections for Decision artifacts.

```bash
rac schema roadmap
```

shows supported relationship sections for Roadmap artifacts.

```bash
rac schema prompt
```

shows supported relationship sections for Prompt artifacts.

```bash
rac inspect requirement.md --json
```

includes a `relationships` field when relationship sections are present.

```bash
rac inspect decision.md --json
```

includes `supersedes` or relationship metadata when present.

Artifacts without relationship sections continue to validate successfully.

Relationship references are not resolved or validated.

No AI services are required.

No graph output is generated.

---

## Future Considerations

Future v0.7.x releases may introduce:

* Relationship inspection across repositories
* Broken relationship detection
* Relationship validation
* Relationship graph export
* Relationship-aware repository summaries
* Relationship-aware portfolio health

These future capabilities should build on the explicit relationship metadata introduced in v0.7.0.
