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

{requirements_as_code-0.6.3/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.3
+Version: 0.7.0
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -460,9 +460,23 @@ 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`, and `designs` are included only when those
-artifacts are present. `stats` exits `0` when the directory has at least one
+`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.)
 
@@ -544,7 +558,9 @@ RAC classifies the document against known artifact schemas (no AI) and reports a
 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 }`.
+`{ 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
 
@@ -623,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,

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

@@ -420,9 +420,23 @@ 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`, and `designs` are included only when those
-artifacts are present. `stats` exits `0` when the directory has at least one
+`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.)
 
@@ -504,7 +518,9 @@ RAC classifies the document against known artifact schemas (no AI) and reports a
 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 }`.
+`{ 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
 
@@ -583,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,

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

requirements_as_code-0.7.0/planning/designs/explorer-first-run-experience.md

@@ -0,0 +1,251 @@
+# Explorer First Run Experience
+
+## Context
+
+RAC Explorer introduces a new way of interacting with product knowledge repositories.
+
+The CLI is optimized for automation:
+
+```text
+Run command
+
+Receive output
+```
+
+Explorer is optimized for exploration:
+
+```text
+Enter workspace
+
+Understand repository
+
+Navigate knowledge
+```
+
+The first launch experience determines whether users understand this distinction.
+
+---
+
+## User Need
+
+Users need to become productive without knowing:
+
+- RAC commands
+- Repository structure
+- Artifact types
+- Relationship concepts
+
+Explorer should guide users from zero context to useful exploration.
+
+---
+
+## Design
+
+## First Launch
+
+Running:
+
+```bash
+rac explorer
+```
+
+without previous context opens onboarding.
+
+Example:
+
+```text
+Welcome to RAC Explorer
+
+Your product knowledge workspace.
+
+
+Choose repository:
+
+> Current directory
+
+  Recent repository
+
+  Browse
+```
+
+---
+
+## Repository Discovery
+
+Explorer checks the selected location.
+
+Possible states:
+
+---
+
+### Existing RAC Repository
+
+Example:
+
+```text
+Repository Found
+
+Analyzing...
+
+✓ Requirements 42
+
+✓ Decisions 12
+
+✓ Relationships 84
+
+
+Press / for anything
+```
+
+---
+
+### Empty Repository
+
+Example:
+
+```text
+No RAC artifacts found.
+
+
+Start by:
+
+> Import documents
+
+  Create artifact
+
+  Open another repository
+```
+
+---
+
+### Invalid Repository
+
+Example:
+
+```text
+Repository issues found
+
+
+3 invalid artifacts
+
+2 broken relationships
+
+
+Open anyway?
+
+> Yes
+
+  View issues
+```
+
+---
+
+## Learning The Interface
+
+Onboarding teaches only essential controls.
+
+Example:
+
+```text
+Navigation
+
+/      Search and commands
+
+↑ ↓    Move
+
+Enter  Open
+
+q      Quit
+```
+
+Do not introduce every feature upfront.
+
+---
+
+## Recent Repositories
+
+Explorer remembers previously opened repositories.
+
+Example:
+
+```text
+Recent
+
+requirements-as-code
+
+payments-platform
+
+identity-service
+```
+
+---
+
+## Returning Users
+
+Skip onboarding.
+
+Restore:
+
+- Last repository
+- Last view
+- Last artifact
+
+Users return directly to work.
+
+---
+
+## Preferences
+
+Optional preferences:
+
+- Theme
+- Default start view
+- Artifact grouping
+
+Preferences must never block onboarding.
+
+---
+
+## Constraints
+
+### Fast Startup
+
+Users should reach repository context within seconds.
+
+---
+
+### No Accounts
+
+Explorer requires:
+
+- No login
+- No cloud connection
+- No synchronization
+
+---
+
+### No Forced Setup
+
+A user can always exit onboarding and manually navigate.
+
+---
+
+## Accessibility
+
+The onboarding flow shall:
+
+- Be keyboard navigable
+- Avoid colour-only status
+- Provide clear text states
+
+---
+
+## Related Requirements
+
+- v0.9.1 Workspace Experience
+
+---
+
+## Related Decisions
+
+- ADR-015 Explorer as Core Consumer