Add --direction UPSTREAM|DOWNSTREAM to collect command

Enable bidirectional traversal for the collect command. UPSTREAM
(default) traverses derivedFrom relations to ancestors. DOWNSTREAM
traverses derive relations to descendants, enabling enumeration of
all children under impact_scope parent entries.

Author: Test User

claude-plugins/commands/collect.md

@@ -1,13 +1,13 @@
 ---
 allowed-tools: Read, Bash(reqvire:*)
 argument-hint: <element-name>
-description: Collect and summarize requirement context via derivedFrom chain
+description: Collect and summarize requirement context via derivedFrom chain (upstream) or derive chain (downstream)
 model: claude-sonnet-4-5
 ---
 
 # Collect Requirement Context
 
-Collect and present a comprehensive summary of requirement context via the derivedFrom chain.
+Collect and present a comprehensive summary of requirement context via the derivedFrom chain (upstream, default) or derive chain (downstream).
 
 ## Model Context
 

claude-plugins/commands/generate-tasks.md

@@ -37,19 +37,24 @@ Generate implementation task plan from requirement changes on a feature branch.
    reqvire change-impact --git-commit=$BASE_COMMIT --json --output /tmp/impact.json
    ```
 
-3. **Review impact scope** (from JSON `impact_scope[]`):
+3. **Review impact scope and enumerate covered elements** (from JSON `impact_scope[]`):
 
-   The `impact_scope` array shows the per-branch common parent requirements covering all impacted elements. Use this to understand the high-level affected model areas before diving into details.
+   The `impact_scope` array shows the per-branch common parent requirements covering all impacted elements. For each scope root, use downstream collect to enumerate all covered children:
+   ```bash
+   reqvire collect "<scope-root-name>" --direction DOWNSTREAM --json --output /tmp/scope_<name>.json
+   ```
+
+   This returns the scope root and all its descendants, giving you the complete list of affected elements under each scope entry.
 
 4. **For each changed requirement:**
 
-   Get full context using collect:
+   Get full upstream context using collect:
    ```bash
    reqvire collect "<requirement-name>" --json --output /tmp/req_<requirement-id>.json
    ```
 
    This provides:
-   - Complete requirement chain via derivedFrom relations
+   - Complete ancestor chain via derivedFrom relations (upstream)
    - All parent requirements for context
    - Refinement elements (specifications, constraints, behaviors) that refine the requirement
    - Attached design documents

claude-plugins/skills/syseng/SKILL.md

@@ -144,29 +144,32 @@ Refinements are owned via `refinedBy` on the requirement (refinement gets auto-g
 3. Never guess - read files before making changes
 4. Validate after each significant change
 5. When reading requirements, always check for **attachments** (documents, diagrams, images)
-6. Use `reqvire collect` to gather full context from requirement chains (ancestors + attachments)
+6. Use `reqvire collect` to gather full context from requirement chains (ancestors or descendants + attachments)
 
 Use `reqvire collect` to gather complete context for a requirement:
 
 ```bash
-# Get full requirement chain with all ancestor content and attachments
+# Get ancestor chain (upstream - default)
 reqvire collect "Feature Requirement"
 
+# Get all descendants (downstream)
+reqvire collect "Feature Requirement" --direction DOWNSTREAM
+
 # JSON format for programmatic use
 reqvire collect "Feature Requirement" --json
+reqvire collect "Feature Requirement" --direction DOWNSTREAM --json
 ```
 
 **When to use collect:**
-- Before implementing a requirement - get full specification context
+- **Upstream (default)**: Get full ancestor specification context before implementing
+- **Downstream**: Enumerate all children under a parent (e.g., from impact_scope entries)
 - When analyzing impact of changes - understand complete requirement chain
 - When creating tasks from requirements - gather all related specifications
 - When reviewing requirements - see full derivation hierarchy with sources
 
-The collect command traverses `derivedFrom` relations upward and includes:
-- All ancestor requirement content
-- Attached markdown files (read as content)
-- Attached refinement elements (specifications, constraints, behaviors)
-- Source citations for traceability
+The collect command supports two directions:
+- **UPSTREAM** (default): Traverses `derivedFrom` relations upward — ancestors, specs, attachments
+- **DOWNSTREAM**: Traverses `derive` relations downward — all children to leaf elements
 
 ## Command Reference
 

claude-plugins/skills/syseng/reference/CreatingTasks.md

@@ -49,31 +49,46 @@ The change-impact command identifies:
 - **Requirement → Implementation**: May need implementation updates
 - **Verification changes**: Generally don't propagate upward
 
+### Step 1.5: Enumerate Covered Elements from Impact Scope
+
+For each entry in `impact_scope[]`, use downstream collect to find all covered children:
+
+```bash
+# Get all descendants under each scope root
+reqvire collect "<scope-root-name>" --direction DOWNSTREAM --json --output /tmp/scope_<name>.json
+```
+
+This ensures no elements are missed — `impact_scope` entries are common parents that may cover multiple added/changed children.
+
 ### Step 2: Gather Full Requirement Context
 
-For each changed requirement, collect complete context:
+For each changed requirement (from `added[]`, `changed[]`, or enumerated via downstream collect), gather upstream context:
 
 ```bash
-# Get full requirement chain with ancestors and attachments
+# Get full ancestor chain with attachments (upstream - default)
 reqvire collect "<requirement-name>" --json --output /tmp/req_<requirement-id>.json
 
 # Also save human-readable format for reference
 reqvire collect "<requirement-name>" > /tmp/req_context_<requirement-id>.md
 
+# Get all descendants under a requirement (downstream)
+reqvire collect "<requirement-name>" --direction DOWNSTREAM --json --output /tmp/req_<requirement-id>_tree.json
+
 # Get direct requirement details
 reqvire search --filter-id="<requirement-id>" --json
 ```
 
 **Why use `reqvire collect` for task generation:**
-- Gathers complete requirement chain via `derivedFrom` relations
-- Shows parent requirements (the "why" context)
+- **Upstream (default)**: Gathers ancestor chain via `derivedFrom` — the "why" context
+- **Downstream**: Enumerates all children via `derive` — find everything under a scope root
 - Includes all specifications and design documents
 - Captures constraints and validation rules
 - Provides full implementation context in one command
 - Saves to `/tmp` for developer reference during implementation
 
 **What collect provides:**
-- All ancestor requirement content
+- **Upstream**: All ancestor requirement content (parent chain to root)
+- **Downstream**: All descendant requirement content (children to leaves)
 - Attached markdown files (read as content)
 - Attached refinement elements (specifications, constraints, behaviors)
 - Source citations for traceability
@@ -205,12 +220,13 @@ When analyzing requirements for task generation:
 | To Understand This | Use This Command |
 |--------------------|------------------|
 | What requirements changed | `reqvire change-impact --git-commit=<hash> --json` |
-| **Full requirement context** | `reqvire collect "<name>" --json --output /tmp/req_<id>.json` |
+| **Full requirement context (ancestors)** | `reqvire collect "<name>" --json --output /tmp/req_<id>.json` |
 | Requirement direct content | `reqvire search --filter-id="<id>" --json` |
 | What verifies a requirement | `reqvire traces --filter-id="<id>" --json` |
 | Which tests to run | Extract `satisfiedBy` from verification via `reqvire search` |
 | Implementation status | Check `satisfiedBy` relations in requirement |
-| Requirement hierarchy | `reqvire collect "<name>"` shows complete derivedFrom chain |
+| Requirement hierarchy (up) | `reqvire collect "<name>"` shows derivedFrom ancestor chain |
+| Requirement hierarchy (down) | `reqvire collect "<name>" --direction DOWNSTREAM` shows all descendants |
 
 **Why use commands instead of reading files:**
 - Automatic relation following

cli/src/cli.rs

@@ -490,12 +490,16 @@ pub enum Commands {
         output: Option<String>,
     },
 
-    /// Collect content from requirement chain via derivedFrom relations
-    #[clap(override_help = "Collect content from requirement chain via derivedFrom relations\n\nCOLLECT OPTIONS:\n      <ELEMENT_NAME>    Name of the requirement element to collect from\n      --json            Output results in JSON format\n      --output <FILE>   Save JSON output to file (requires --json)")]
+    /// Collect content from requirement chain
+    #[clap(override_help = "Collect content from requirement chain\n\nCOLLECT OPTIONS:\n      <ELEMENT_NAME>        Name of the requirement element to collect from\n      --direction <DIR>     Traversal direction: UPSTREAM (default) or DOWNSTREAM\n      --json                Output results in JSON format\n      --output <FILE>       Save JSON output to file (requires --json)")]
     Collect {
         /// Name of the requirement element to collect from
         element_name: String,
 
+        /// Traversal direction: UPSTREAM (ancestors) or DOWNSTREAM (descendants)
+        #[clap(long, value_name = "DIRECTION", default_value = "UPSTREAM", help_heading = "COLLECT OPTIONS")]
+        direction: String,
+
         /// Output results in JSON format
         #[clap(long, help_heading = "COLLECT OPTIONS")]
         json: bool,
@@ -1365,14 +1369,23 @@ pub fn handle_command(
             }
             return Ok(0);
         },
-        Some(Commands::Collect { element_name, json, output }) => {
+        Some(Commands::Collect { element_name, direction, json, output }) => {
             validate_output_requires_json(&output, json)?;
+            let collect_direction = match direction.to_uppercase().as_str() {
+                "UPSTREAM" => report_collect::CollectDirection::Upstream,
+                "DOWNSTREAM" => report_collect::CollectDirection::Downstream,
+                _ => {
+                    eprintln!("error: invalid direction '{}'. Valid values: UPSTREAM, DOWNSTREAM", direction);
+                    return Ok(1);
+                }
+            };
             let git_root = git_commands::get_git_root_dir()?;
             let report_output = report_collect::generate_collect_report(
                 &model_manager.graph_registry,
                 &element_name,
                 &git_root,
                 json,
+                collect_direction,
             )?;
             if json {
                 handle_json_output(&report_output, &output)?;

core/src/report_collect.rs

@@ -7,6 +7,25 @@ use std::collections::HashSet;
 use std::fs;
 use std::path::Path;
 
+/// Direction of traversal for content collection
+#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum CollectDirection {
+    /// Traverse derivedFrom relations upward to ancestors (default)
+    Upstream,
+    /// Traverse derive relations downward to descendants
+    Downstream,
+}
+
+impl std::fmt::Display for CollectDirection {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            CollectDirection::Upstream => write!(f, "upstream"),
+            CollectDirection::Downstream => write!(f, "downstream"),
+        }
+    }
+}
+
 /// Source type for collected content items
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "snake_case")]
@@ -50,6 +69,7 @@ pub struct CollectMetadata {
 #[derive(Debug, Serialize)]
 pub struct CollectReport {
     pub starting_element: String,
+    pub direction: CollectDirection,
     pub items: Vec<CollectedItem>,
     pub metadata: CollectMetadata,
 }
@@ -60,6 +80,7 @@ pub fn generate_collect_report(
     element_name: &str,
     git_root: &Path,
     json_output: bool,
+    direction: CollectDirection,
 ) -> Result<String, ReqvireError> {
     // Find element by name
     let element_id = registry
@@ -95,18 +116,26 @@ pub fn generate_collect_report(
         }
     }
 
-    // Collect ancestor chain via derivedFrom relations
-    let ancestor_chain = collect_ancestor_chain(registry, &element_id);
+    // Collect chain based on direction
+    let chain = match direction {
+        CollectDirection::Upstream => collect_ancestor_chain(registry, &element_id),
+        CollectDirection::Downstream => collect_descendant_chain(registry, &element_id),
+    };
 
     // Build collected items
     let mut items: Vec<CollectedItem> = Vec::new();
     let mut element_count = 0;
     let mut refinement_count = 0;
     let mut attachment_count = 0;
 
-    // Process ancestors first (root first, depth 0)
-    // ancestor_chain is ordered from starting element to root, so we reverse
-    for (depth, elem_id) in ancestor_chain.iter().rev().enumerate() {
+    // For upstream: chain is start→root, reverse to get root first (depth 0)
+    // For downstream: chain is already start→leaves (start at depth 0)
+    let ordered_chain: Vec<&String> = match direction {
+        CollectDirection::Upstream => chain.iter().rev().collect(),
+        CollectDirection::Downstream => chain.iter().collect(),
+    };
+
+    for (depth, elem_id) in ordered_chain.iter().enumerate() {
         if let Some(elem) = registry.get_element(elem_id) {
             // Add element content
             items.push(CollectedItem {
@@ -147,6 +176,7 @@ pub fn generate_collect_report(
 
     let report = CollectReport {
         starting_element: element_id,
+        direction,
         items,
         metadata: CollectMetadata {
             element_count,
@@ -206,6 +236,47 @@ fn collect_ancestor_chain(registry: &GraphRegistry, start_id: &str) -> Vec<Strin
     chain
 }
 
+/// Collect the descendant chain following derive relations (parent to children)
+fn collect_descendant_chain(registry: &GraphRegistry, start_id: &str) -> Vec<String> {
+    let mut chain = Vec::new();
+    let mut visited = HashSet::new();
+    let mut current_level = vec![start_id.to_string()];
+
+    while !current_level.is_empty() {
+        // Sort for deterministic ordering
+        let mut sorted_level = current_level.clone();
+        sorted_level.sort();
+
+        for elem_id in &sorted_level {
+            if visited.contains(elem_id) {
+                continue;
+            }
+            visited.insert(elem_id.clone());
+            chain.push(elem_id.clone());
+        }
+
+        // Find next level (children via derive)
+        let mut next_level = Vec::new();
+        for elem_id in &sorted_level {
+            if let Some(elem) = registry.get_element(elem_id) {
+                for rel in &elem.relations {
+                    if rel.relation_type.name == "derive" {
+                        if let relation::LinkType::Identifier(target_id) = &rel.target.link {
+                            if !visited.contains(target_id) {
+                                next_level.push(target_id.clone());
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        current_level = next_level;
+    }
+
+    chain
+}
+
 /// Collect content from an attachment
 fn collect_attachment_content(
     registry: &GraphRegistry,
@@ -481,6 +552,12 @@ fn extract_element_name(identifier: &str) -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn test_collect_direction_display() {
+        assert_eq!(format!("{}", CollectDirection::Upstream), "upstream");
+        assert_eq!(format!("{}", CollectDirection::Downstream), "downstream");
+    }
+
     #[test]
     fn test_extract_element_name() {
         assert_eq!(

requirements/Functional/Output/Reporting.md

@@ -28,12 +28,13 @@ When requested the system shall provide human readable and machine readable Syst
 
 ### Collect Content from Requirement Chain
 
-The system shall collect and consolidate all content from a requirement element and its ancestors via derivedFrom relations, including refinedBy targets (refinement elements and specification files) and attachment contents, and output with source citations in text or JSON format.
+The system shall collect and consolidate all content from a requirement element and its related requirements via derivedFrom relations (upstream to ancestors) or derive relations (downstream to descendants), including refinedBy targets (refinement elements and specification files) and attachment contents, and output with source citations in text or JSON format.
 
 #### Details
 The system shall define:
 - Content collection rules for elements, refinedBy targets, and attachments
 - Output format specifications for text and JSON modes
+- Direction-based traversal: upstream (ancestors via derivedFrom) or downstream (descendants via derive)
 
 #### Metadata
   * type: requirement

requirements/Functional/Output/Specifications.md

@@ -13,8 +13,12 @@ Technical specification for content collection from requirement chains.
 
 **Traversal Rules:**
 - Start from specified requirement element
-- Traverse derivedFrom relations in reverse direction (child to parents)
-- Continue until root ancestors reached (elements with no derivedFrom)
+- When direction is UPSTREAM (default):
+  - Traverse derivedFrom relations in reverse direction (child to parents)
+  - Continue until root ancestors reached (elements with no derivedFrom)
+- When direction is DOWNSTREAM:
+  - Traverse derive relations in forward direction (parent to children)
+  - Continue until leaf descendants reached (elements with no derive to other requirements)
 - Include the starting element in output
 
 **Content Collection:**
@@ -31,8 +35,9 @@ Technical specification for content collection from requirement chains.
 
 **Output Ordering:**
 - Flat list structure (no nesting)
-- Ancestors first (depth 0 = root), then descendants
-- Same-level elements sorted alphabetically by name or file path
+- When direction is UPSTREAM: ancestors first (depth 0 = root), then starting element
+- When direction is DOWNSTREAM: starting element first (depth 0), then descendants at increasing depth
+- Same-depth elements sorted alphabetically by name or file path
 
 **Error Handling:**
 - Element not found: Error with message