---
schema_version: 1
id: RAC-KTQ63DVVW9WZ
type: requirement
---
# RAC v0.4.2 — Decision Metadata

## Context

v0.4.0 introduced artifact inspection.

v0.4.1 expanded inspection to repository-level analysis.

Decision artifacts are now supported and can be validated, inspected, counted, and classified.

However, decision repositories remain largely collections of independent documents.

RAC currently has no understanding of:

- Decision status
- Decision categories
- Superseded decisions

As a result, users cannot distinguish active decisions from historical decisions, group decisions by type, or identify obsolete records.

This release introduces lightweight decision metadata while remaining fully file-first and AI-optional.

---

## Problem

Decision repositories frequently contain:

- Active decisions
- Deprecated decisions
- Superseded decisions
- Product decisions
- Process decisions
- Technical decisions

Without metadata, all decisions appear equivalent.

Users must manually inspect documents to understand their relevance and status.

---

## Goals

Introduce optional metadata for Decision artifacts.

Support:

- Decision status
- Decision category
- Supersession references
- Repository-level decision analysis

without:

- Relationship graphs
- Knowledge maps
- AI classification
- Cross-artifact analysis

---

## Requirements

### REQ-001 — Decision Status

Decision artifacts may contain:

```markdown
## Status

Proposed
```

Supported values:

- Proposed
- Accepted
- Superseded
- Deprecated

Validation shall verify supported values.

---

### REQ-002 — Decision Category

Decision artifacts may contain:

```markdown
## Category

Architecture
```

Supported values:

- Architecture
- Product
- Process
- Technical
- Other

Validation shall verify supported values.

---

### REQ-003 — Supersedes Reference

Decision artifacts may contain:

```markdown
## Supersedes

ADR-012
```

The field shall be treated as metadata only.

Validation shall not verify existence.

---

### REQ-004 — Repository Statistics

`rac stats`

shall report decision metadata counts.

Example:

```text
Decisions

Status
- Accepted: 12
- Proposed: 3
- Superseded: 2

Category
- Architecture: 8
- Product: 5
- Process: 4
```

---

### REQ-005 — Inspection Support

`rac inspect`

shall identify:

- Status
- Category
- Supersedes

when present.

Human output may display:

```text
Type: Decision

Status: Accepted
Category: Architecture
Supersedes: ADR-004
```

JSON output shall include metadata.

---

### REQ-006 — Schema Support

Decision schemas shall be updated to include:

Required:

- Context
- Decision
- Consequences

Recommended:

- Status
- Category

Optional:

- Supersedes

---

### REQ-007 — Backwards Compatibility

Missing metadata shall not invalidate a decision artifact.

Existing decision documents remain valid.

---

## Non-Goals

### Relationship Analysis

Not:

```bash
rac relationships .
```

---

### Supersession Validation

Not:

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

---

### Automatic Categorization

Not:

```text
This looks like an Architecture decision.
```

---

### Knowledge Graphs

Not:

```text
ADR-001 → ADR-004 → ADR-008
```

---

## Success Metrics

### Functional

- Decision status can be represented consistently.
- Decision categories can be reported consistently.
- Superseded decisions can be identified quickly.
- Existing ADRs continue to validate successfully.

### Product

Users can distinguish active decisions from historical decisions without opening individual files.

Users can understand the composition of decision repositories through repository statistics.

---

## Risks

- Users may apply categories inconsistently.
- Different teams may interpret status values differently.
- Metadata may become stale if not maintained.

---

## Acceptance Criteria

```bash
rac validate adr-001.md
```

validates status and category values.

```bash
rac inspect adr-001.md
```

shows metadata when present.

```bash
rac inspect rac/decisions
```

includes metadata in repository inspection results.

```bash
rac stats .
```

reports decision status and category counts.

Decision documents without metadata remain valid.

No AI services are required.