requirements-as-code 0.6.2__tar.gz → 0.7.0__tar.gz

{requirements_as_code-0.6.2/requirements_as_code.egg-info → requirements_as_code-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.6.2
+Version: 0.7.0
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -423,9 +423,12 @@ Counts span all parsed requirement files; a feature with only *warnings* (e.g. n
 metrics) still counts as valid. Invalid files are listed at the end so they are
 never silently skipped.
 
-Decision artifacts are aggregated **separately** so they never distort the
-requirement totals or averages. When a directory contains decisions, a
-`Decisions` section reports the count plus a status and category breakdown:
+Non-requirement artifacts are aggregated **separately** so they never distort the
+requirement totals or averages. Decisions report metadata breakdowns; Roadmaps,
+Prompts, and Designs use lightweight count/valid/invalid summaries.
+
+When a directory contains decisions, a `Decisions` section reports the count plus
+a status and category breakdown:
 
 ```text
 Decisions
@@ -444,11 +447,38 @@ Category
   - Process: 4
 ```
 
-Add `--json` for machine-readable output (a `decisions` block is included only
-when decisions are present). `stats` exits `0` when the directory has at least
-one valid feature or decision, `1` if none, and `2` if the path is not a
-directory. (A `--strict` flag for failing on *any* invalid file — handy in CI —
-is planned.)
+When a directory contains Design artifacts, a lightweight section is shown:
+
+```text
+Designs
+=======
+
+Total: 4
+Valid: 3
+
+Invalid Designs (1)
+  ./planning/design/draft.md — missing-constraints
+```
+
+When artifacts declare [relationship metadata](#relationship-metadata), a
+`Relationships` section reports **declared-presence counts** — how many artifacts
+contain each relationship section with at least one reference. These are presence
+counts, not resolved links or edge totals:
+
+```text
+Relationships
+=============
+
+Artifacts with Related Decisions: 6
+Artifacts with Related Requirements: 4
+Artifacts with Supersedes: 2
+```
+
+Add `--json` for machine-readable output. Artifact-specific blocks such as
+`decisions`, `roadmaps`, `prompts`, `designs`, and `relationships` are included
+only when those artifacts (or relationship sections) are present. `stats` exits `0` when the directory has at least one
+valid known artifact, `1` if none, and `2` if the path is not a directory. (A
+`--strict` flag for failing on *any* invalid file — handy in CI — is planned.)
 
 ---
 
@@ -525,10 +555,12 @@ Missing Sections:
 ```
 
 RAC classifies the document against known artifact schemas (no AI) and reports a
-confidence score. v0.4 recognizes **Requirement** and **Decision** artifacts;
-anything that doesn't fit well is reported as **Unknown** (a valid, successful
-result — not an error). `--json` emits `{ type, confidence, present_sections,
-missing_sections }`.
+confidence score. RAC recognizes **Requirement**, **Decision**, **Roadmap**,
+**Prompt**, and **Design** artifacts; anything that doesn't fit well is reported
+as **Unknown** (a valid, successful result — not an error). `--json` emits
+`{ type, confidence, present_sections, missing_sections }`, plus an additive
+`relationships` object when the artifact declares relationship sections (see
+[Relationship metadata](#relationship-metadata)).
 
 ### Inspect a directory
 
@@ -546,7 +578,10 @@ Files Inspected: 23
 
 Requirements: 7
 Decisions: 3
-Unknown: 13
+Roadmaps: 2
+Prompts: 4
+Designs: 1
+Unknown: 6
 ```
 
 ### Explain a classification (`--verbose`)
@@ -604,6 +639,57 @@ ADR-012
 or Category value fails validation (`invalid-decision-status` /
 `invalid-decision-category`); values are matched case-insensitively.
 
+### Relationship metadata
+
+Artifacts can reference each other with explicit Markdown sections (v0.7.0). RAC
+extracts these as **metadata only** — it records the references but does **not**
+resolve, validate, or graph them (those come in a later v0.7.x release).
+
+```markdown
+## Related Decisions
+
+- ADR-004
+- ADR-012
+
+## Related Roadmaps
+
+- ROADMAP-Q3-PLATFORM
+```
+
+Each artifact type recognizes the relationship sections that make sense for it:
+
+| Artifact | Relationship sections |
+|-------------|--------------------------------------------------------------------------|
+| Requirement | Related Decisions, Related Roadmaps, Related Prompts, Related Designs |
+| Decision | Supersedes, Related Requirements, Related Roadmaps, Related Designs |
+| Roadmap | Related Decisions, Related Requirements, Related Prompts, Related Designs |
+| Prompt | Related Requirements, Related Decisions, Related Roadmaps, Related Designs |
+| Design | Related Requirements, Related Decisions, Related Roadmaps, Related Prompts |
+
+Relationship sections are **optional**: they are never scored, never reported as
+missing, and never appear in starter templates — an artifact without them stays
+valid. `inspect` surfaces them under a **Relationships** block, and in `--json`
+as an additive `relationships` object (snake_case keys, string arrays, present
+only when at least one reference is declared):
+
+```json
+{
+  "type": "requirement",
+  "present_sections": ["problem", "requirements"],
+  "relationships": {
+    "related_decisions": ["ADR-004", "ADR-012"],
+    "related_roadmaps": ["ROADMAP-Q3-PLATFORM"]
+  }
+}
+```
+
+References are kept verbatim (an `ADR-004`, a `REQ-001`, or a relative path are
+all valid) — RAC does not parse out IDs or check that the targets exist.
+
+**`supersedes` is a backwards-compatible exception:** it remains a top-level
+scalar (`"supersedes": "ADR-012"`) rather than moving into `relationships`, so the
+existing Decision contract is unchanged.
+
 ### Synonyms
 
 Common heading variants are recognized automatically (case-insensitive,
@@ -686,10 +772,10 @@ So you can go straight from `rac inspect requirement.md` to
 ```
 
 `improve` generates suggestions for artifact types with complete schema guidance
-coverage. Today that means **Requirement** and **Decision** artifacts. Unknown
-documents return a short explanatory message instead. Future artifact types do
-not become improvable until their schemas define guidance for every required and
-recommended section.
+coverage. Today that means **Requirement**, **Decision**, **Roadmap**, **Prompt**,
+and **Design** artifacts. Unknown documents return a short explanatory message
+instead. Future artifact types do not become improvable until their schemas
+define guidance for every required and recommended section.
 
 Guidance is informational metadata only: it does not influence classification,
 validation, confidence scoring, statistics, or repository analysis.
@@ -709,11 +795,15 @@ rac schema --list
 rac schema --list --json
 rac schema requirement
 rac schema decision --json
+rac schema design
 rac schema requirement --template
+rac schema design --template
 ```
 
 `rac schema <type>` shows the full schema reference: required, recommended, and
 optional sections; descriptions; guidance; and metadata values where applicable.
+Supported schemas are `requirement`, `decision`, `roadmap`, `prompt`, and
+`design`.
 
 ```text
 Artifact Type: Decision
@@ -757,6 +847,7 @@ meaningful product knowledge.
 ```bash
 rac schema requirement --template > requirement.md
 rac schema decision --template > decision.md
+rac schema design --template > design.md
 ```
 
 Generated templates are validation-safe:
@@ -764,6 +855,7 @@ Generated templates are validation-safe:
 ```bash
 rac schema requirement --template | rac validate -
 rac schema decision --template | rac validate -
+rac schema design --template | rac validate -
 ```
 
 Unknown schemas fail with exit code `2` and list available schemas. Only

{requirements_as_code-0.6.2 → requirements_as_code-0.7.0}/README.md

@@ -383,9 +383,12 @@ Counts span all parsed requirement files; a feature with only *warnings* (e.g. n
 metrics) still counts as valid. Invalid files are listed at the end so they are
 never silently skipped.
 
-Decision artifacts are aggregated **separately** so they never distort the
-requirement totals or averages. When a directory contains decisions, a
-`Decisions` section reports the count plus a status and category breakdown:
+Non-requirement artifacts are aggregated **separately** so they never distort the
+requirement totals or averages. Decisions report metadata breakdowns; Roadmaps,
+Prompts, and Designs use lightweight count/valid/invalid summaries.
+
+When a directory contains decisions, a `Decisions` section reports the count plus
+a status and category breakdown:
 
 ```text
 Decisions
@@ -404,11 +407,38 @@ Category
   - Process: 4
 ```
 
-Add `--json` for machine-readable output (a `decisions` block is included only
-when decisions are present). `stats` exits `0` when the directory has at least
-one valid feature or decision, `1` if none, and `2` if the path is not a
-directory. (A `--strict` flag for failing on *any* invalid file — handy in CI —
-is planned.)
+When a directory contains Design artifacts, a lightweight section is shown:
+
+```text
+Designs
+=======
+
+Total: 4
+Valid: 3
+
+Invalid Designs (1)
+  ./planning/design/draft.md — missing-constraints
+```
+
+When artifacts declare [relationship metadata](#relationship-metadata), a
+`Relationships` section reports **declared-presence counts** — how many artifacts
+contain each relationship section with at least one reference. These are presence
+counts, not resolved links or edge totals:
+
+```text
+Relationships
+=============
+
+Artifacts with Related Decisions: 6
+Artifacts with Related Requirements: 4
+Artifacts with Supersedes: 2
+```
+
+Add `--json` for machine-readable output. Artifact-specific blocks such as
+`decisions`, `roadmaps`, `prompts`, `designs`, and `relationships` are included
+only when those artifacts (or relationship sections) are present. `stats` exits `0` when the directory has at least one
+valid known artifact, `1` if none, and `2` if the path is not a directory. (A
+`--strict` flag for failing on *any* invalid file — handy in CI — is planned.)
 
 ---
 
@@ -485,10 +515,12 @@ Missing Sections:
 ```
 
 RAC classifies the document against known artifact schemas (no AI) and reports a
-confidence score. v0.4 recognizes **Requirement** and **Decision** artifacts;
-anything that doesn't fit well is reported as **Unknown** (a valid, successful
-result — not an error). `--json` emits `{ type, confidence, present_sections,
-missing_sections }`.
+confidence score. RAC recognizes **Requirement**, **Decision**, **Roadmap**,
+**Prompt**, and **Design** artifacts; anything that doesn't fit well is reported
+as **Unknown** (a valid, successful result — not an error). `--json` emits
+`{ type, confidence, present_sections, missing_sections }`, plus an additive
+`relationships` object when the artifact declares relationship sections (see
+[Relationship metadata](#relationship-metadata)).
 
 ### Inspect a directory
 
@@ -506,7 +538,10 @@ Files Inspected: 23
 
 Requirements: 7
 Decisions: 3
-Unknown: 13
+Roadmaps: 2
+Prompts: 4
+Designs: 1
+Unknown: 6
 ```
 
 ### Explain a classification (`--verbose`)
@@ -564,6 +599,57 @@ ADR-012
 or Category value fails validation (`invalid-decision-status` /
 `invalid-decision-category`); values are matched case-insensitively.
 
+### Relationship metadata
+
+Artifacts can reference each other with explicit Markdown sections (v0.7.0). RAC
+extracts these as **metadata only** — it records the references but does **not**
+resolve, validate, or graph them (those come in a later v0.7.x release).
+
+```markdown
+## Related Decisions
+
+- ADR-004
+- ADR-012
+
+## Related Roadmaps
+
+- ROADMAP-Q3-PLATFORM
+```
+
+Each artifact type recognizes the relationship sections that make sense for it:
+
+| Artifact | Relationship sections |
+|-------------|--------------------------------------------------------------------------|
+| Requirement | Related Decisions, Related Roadmaps, Related Prompts, Related Designs |
+| Decision | Supersedes, Related Requirements, Related Roadmaps, Related Designs |
+| Roadmap | Related Decisions, Related Requirements, Related Prompts, Related Designs |
+| Prompt | Related Requirements, Related Decisions, Related Roadmaps, Related Designs |
+| Design | Related Requirements, Related Decisions, Related Roadmaps, Related Prompts |
+
+Relationship sections are **optional**: they are never scored, never reported as
+missing, and never appear in starter templates — an artifact without them stays
+valid. `inspect` surfaces them under a **Relationships** block, and in `--json`
+as an additive `relationships` object (snake_case keys, string arrays, present
+only when at least one reference is declared):
+
+```json
+{
+  "type": "requirement",
+  "present_sections": ["problem", "requirements"],
+  "relationships": {
+    "related_decisions": ["ADR-004", "ADR-012"],
+    "related_roadmaps": ["ROADMAP-Q3-PLATFORM"]
+  }
+}
+```
+
+References are kept verbatim (an `ADR-004`, a `REQ-001`, or a relative path are
+all valid) — RAC does not parse out IDs or check that the targets exist.
+
+**`supersedes` is a backwards-compatible exception:** it remains a top-level
+scalar (`"supersedes": "ADR-012"`) rather than moving into `relationships`, so the
+existing Decision contract is unchanged.
+
 ### Synonyms
 
 Common heading variants are recognized automatically (case-insensitive,
@@ -646,10 +732,10 @@ So you can go straight from `rac inspect requirement.md` to
 ```
 
 `improve` generates suggestions for artifact types with complete schema guidance
-coverage. Today that means **Requirement** and **Decision** artifacts. Unknown
-documents return a short explanatory message instead. Future artifact types do
-not become improvable until their schemas define guidance for every required and
-recommended section.
+coverage. Today that means **Requirement**, **Decision**, **Roadmap**, **Prompt**,
+and **Design** artifacts. Unknown documents return a short explanatory message
+instead. Future artifact types do not become improvable until their schemas
+define guidance for every required and recommended section.
 
 Guidance is informational metadata only: it does not influence classification,
 validation, confidence scoring, statistics, or repository analysis.
@@ -669,11 +755,15 @@ rac schema --list
 rac schema --list --json
 rac schema requirement
 rac schema decision --json
+rac schema design
 rac schema requirement --template
+rac schema design --template
 ```
 
 `rac schema <type>` shows the full schema reference: required, recommended, and
 optional sections; descriptions; guidance; and metadata values where applicable.
+Supported schemas are `requirement`, `decision`, `roadmap`, `prompt`, and
+`design`.
 
 ```text
 Artifact Type: Decision
@@ -717,6 +807,7 @@ meaningful product knowledge.
 ```bash
 rac schema requirement --template > requirement.md
 rac schema decision --template > decision.md
+rac schema design --template > design.md
 ```
 
 Generated templates are validation-safe:
@@ -724,6 +815,7 @@ Generated templates are validation-safe:
 ```bash
 rac schema requirement --template | rac validate -
 rac schema decision --template | rac validate -
+rac schema design --template | rac validate -
 ```
 
 Unknown schemas fail with exit code `2` and list available schemas. Only

requirements_as_code-0.7.0/planning/designs/explorer-command-surface.md

@@ -0,0 +1,270 @@
+# Explorer Command Surface
+
+## Context
+
+RAC Explorer provides a terminal-native workspace for navigating product knowledge repositories.
+
+Traditional command-line interfaces require users to remember commands:
+
+```text
+rac inspect
+
+rac relationships
+
+rac portfolio
+```
+
+Explorer should instead provide a discoverable interaction model where users express intent and navigate from a single entry point.
+
+The command surface is inspired by modern developer tools such as:
+
+- Claude Code
+- Amp
+- Command palettes
+- Terminal-native workflows
+
+---
+
+## User Need
+
+Users need a fast way to:
+
+- Find artifacts
+- Navigate repository knowledge
+- Execute RAC workflows
+- Discover available capabilities
+
+without memorizing command syntax or navigating deep menus.
+
+---
+
+## Design
+
+### Primary Interaction
+
+The primary command entry point is:
+
+```text
+/
+```
+
+Typing `/` opens the command surface.
+
+Example:
+
+```text
+/
+
+open req-001
+
+payments
+
+validate repository
+
+import document
+```
+
+---
+
+## Unified Search and Commands
+
+Search and actions share one interface.
+
+The user should not need to decide:
+
+```text
+Am I searching?
+
+or
+
+Am I running a command?
+```
+
+Explorer resolves intent.
+
+---
+
+## Command Registry
+
+All Explorer actions are registered through a single command registry.
+
+Examples:
+
+```text
+open
+
+search
+
+validate
+
+import
+
+relationships
+
+health
+```
+
+An action not registered in the command surface is considered undiscoverable.
+
+---
+
+## Artifact Navigation
+
+Artifact lookup should support:
+
+```text
+REQ-001
+
+ADR-004
+
+payments
+```
+
+Results may include:
+
+```text
+Requirements
+
+REQ-001 Payment Retry Logic
+
+
+Decisions
+
+ADR-004 Payment Provider Choice
+```
+
+---
+
+## Operational Commands
+
+Repository operations should be accessible.
+
+Examples:
+
+```text
+/validate
+
+/improve req-001
+
+/import
+
+/health
+```
+
+Explorer invokes RAC Core services.
+
+Explorer does not implement operation logic.
+
+---
+
+## Keyboard Model
+
+Primary:
+
+```text
+/      Command
+
+↑ ↓    Navigate
+
+Enter  Select
+
+Esc    Back
+
+q      Quit
+```
+
+Additional shortcuts may exist only for high-frequency actions.
+
+---
+
+## Empty States
+
+The command surface should teach users.
+
+Example:
+
+```text
+Start typing...
+
+Try:
+
+open req-001
+
+validate
+
+import document
+```
+
+---
+
+## Constraints
+
+### Single Interaction Model
+
+Do not introduce:
+
+- Separate search boxes
+- Separate command palettes
+- Feature-specific menus
+
+The slash command is the universal entry point.
+
+---
+
+### No Intelligence Ownership
+
+Command routing may happen in Explorer.
+
+Repository answers come from RAC Core.
+
+---
+
+### Terminal Native
+
+Interactions must work:
+
+- Without mouse
+- Over SSH
+- In constrained terminals
+
+---
+
+## Accessibility
+
+Command results shall not rely on colour alone.
+
+Examples:
+
+Preferred:
+
+```text
+✓ Valid
+
+! Warning
+
+✗ Error
+```
+
+Avoid:
+
+```text
+Green item
+
+Yellow item
+
+Red item
+```
+
+---
+
+## Related Requirements
+
+- v0.9.0 Explorer Foundation
+- v0.9.2 Knowledge Operations
+
+---
+
+## Related Decisions
+
+- ADR-015 Explorer as Core Consumer
+- ADR-016 Explorer Adapter Boundary