ralphx 0.2.2__py3-none-any.whl → 0.3.5__py3-none-any.whl

ralphx/core/executor.py

@@ -763,9 +763,6 @@ class LoopExecutor:
             template = template.replace("{{input_item.title}}", title)
             template = template.replace("{{input_item}}", content)  # Alias
             template = template.replace("{{workflow_id}}", workflow_id_val)
-            # Backward compatibility for old templates using namespace/source_loop
-            template = template.replace("{{namespace}}", workflow_id_val)
-            template = template.replace("{{source_loop}}", workflow_id_val)
 
             # hank-rcm style variables (for PROMPT_IMPL.md compatibility)
             # Using {VAR} format to match ralph_impl.sh templates exactly

ralphx/core/loop.py

@@ -188,11 +188,15 @@ class LoopLoader:
     def register_loop(
         self,
         config: LoopConfig,
+        workflow_id: Optional[str] = None,
+        step_id: Optional[int] = None,
     ) -> str:
         """Register a loop configuration in the database.
 
         Args:
             config: Validated loop configuration.
+            workflow_id: Parent workflow ID. Required for workflow-first architecture.
+            step_id: Parent workflow step ID. Required for workflow-first architecture.
 
         Returns:
             The loop ID.
@@ -213,6 +217,8 @@ class LoopLoader:
             id=loop_id,
             name=config.name,
             config_yaml=config.to_yaml(),
+            workflow_id=workflow_id,
+            step_id=step_id,
         )
         return loop_id
 
@@ -287,11 +293,18 @@ class LoopLoader:
 
         return sorted(set(loop_files))
 
-    def sync_loops(self, project: Project) -> dict:
+    def sync_loops(
+        self,
+        project: Project,
+        workflow_id: Optional[str] = None,
+        step_id: Optional[int] = None,
+    ) -> dict:
         """Sync loop configurations from project files to database.
 
         Args:
             project: Project to sync.
+            workflow_id: Parent workflow ID. Required for workflow-first architecture.
+            step_id: Parent workflow step ID. Required for workflow-first architecture.
 
         Returns:
             Dictionary with sync results (added, updated, removed counts).
@@ -312,7 +325,7 @@ class LoopLoader:
 
                 # Check if already exists
                 existing = self._require_db().get_loop(config.name)
-                self.register_loop(config)
+                self.register_loop(config, workflow_id=workflow_id, step_id=step_id)
 
                 if existing:
                     updated += 1

ralphx/core/loop_templates.py

@@ -227,6 +227,72 @@ Return your findings as JSON:
 """
 
 
+# ============================================================================
+# Web-Generated Requirements Prompt
+# ============================================================================
+
+WEBGEN_REQUIREMENTS_PROMPT = """# Web-Generated Requirements Discovery
+
+You are researching industry best practices to find requirements MISSING from the design document.
+
+## Design Document Summary
+{{design_doc_summary}}
+
+## Existing Stories (DO NOT DUPLICATE)
+Total: {{total_stories}}
+{{existing_stories}}
+
+## Category Statistics (for ID assignment)
+{{category_stats}}
+
+## Your Task
+
+1. **Identify the domain** from the design document (e.g., "e-commerce", "healthcare", "fintech")
+2. **Research** using WebSearch:
+   - "{domain} application best practices {{current_year}}"
+   - "{domain} security requirements"
+   - "{domain} compliance regulations"
+   - "common {domain} features users expect"
+3. **Find gaps** - requirements NOT in existing stories
+4. **Generate stories** for those gaps
+
+## Output Format
+
+```json
+{
+  "domain_identified": "e-commerce",
+  "searches_performed": ["e-commerce best practices 2026", "..."],
+  "gaps_found": [
+    {"gap": "No rate limiting", "source": "OWASP guidelines"},
+    {"gap": "Missing GDPR compliance", "source": "EU regulations"}
+  ],
+  "stories": [
+    {
+      "id": "SEC-045",
+      "title": "Implement rate limiting",
+      "content": "As a system administrator, I want rate limiting on API endpoints so that the system is protected from abuse.",
+      "acceptance_criteria": ["Rate limit of 100 req/min per user", "429 response when exceeded", "Configurable limits"],
+      "priority": 2,
+      "category": "SEC",
+      "complexity": "medium",
+      "source": "webgen_requirements",
+      "rationale": "OWASP recommends rate limiting for all public APIs"
+    }
+  ]
+}
+```
+
+## Rules
+
+1. Use standard CATEGORY-NNN IDs (check category_stats for next number)
+2. Add `"source": "webgen_requirements"` to each story's metadata
+3. Include `rationale` explaining WHY this requirement matters
+4. If web search returns nothing useful, return empty stories array with explanation
+5. DO NOT duplicate existing stories - check IDs and titles carefully
+6. Focus on GAPS - things genuinely missing, not rephrasing existing stories
+"""
+
+
 # ============================================================================
 # Implementation Loop Template
 # ============================================================================
@@ -684,7 +750,7 @@ limits:
 
 def generate_simple_implementation_config(
     name: str,
-    namespace: Optional[str] = None,
+    source_loop: Optional[str] = None,
     display_name: str = "Implementation",
     description: str = "",
     max_iterations: Optional[int] = None,
@@ -695,7 +761,7 @@ def generate_simple_implementation_config(
 
     Args:
         name: Unique loop ID (auto-generated, e.g., implementation-20260115_1).
-        namespace: Namespace to consume stories from.
+        source_loop: Source loop name to consume items from.
         display_name: User-facing name (can be duplicated across loops).
         description: Optional user-provided description.
         max_iterations: Override for max iterations (default: 50).
@@ -705,7 +771,7 @@ def generate_simple_implementation_config(
     Returns:
         YAML configuration string.
     """
-    source_section = f"    source: {namespace}" if namespace else ""
+    source_section = f"    source: {source_loop}" if source_loop else ""
     desc_line = description if description else "Implement user stories as working code"
 
     # Apply defaults if not specified

ralphx/core/planning_service.py

@@ -64,25 +64,109 @@ This format is machine-parsed. Non-compliance breaks the system.
 # =============================================================================
 
 PLANNING_BEHAVIOR = '''<behavior>
-You are a product planning assistant helping users design software products.
-
-Your role is to:
-1. Understand what the user wants to build
-2. Ask clarifying questions about requirements, users, and scope
-3. Help them think through the architecture and design
-4. Eventually produce a comprehensive design document
-
-Guidelines:
-- Ask focused, specific questions (2-3 at a time max)
-- Summarize your understanding periodically
-- Be conversational but efficient
-- Focus on: problem space, target users, core features, technical constraints
-- When the user is ready, offer to generate the design document
-
-Do NOT:
-- Write code unless explicitly asked
-- Make assumptions without confirming
-- Overwhelm with too many questions at once
+You are an expert product architect and technical consultant helping users design
+software products. You combine deep technical knowledge with strong product sense.
+
+## Your Core Mission
+
+Transform vague ideas into comprehensive, implementable design documents through
+collaborative discovery. You're not just a Q&A bot—you're a thinking partner who
+challenges assumptions, identifies blind spots, and brings industry expertise.
+
+## Discovery Phases
+
+Work through these phases naturally (you don't need to announce them):
+
+### Phase 1: Problem Space Understanding
+- What problem are we solving? Why does it matter?
+- Who experiences this problem? (specific personas, not generic "users")
+- What do they currently do? What's broken about that?
+- What would success look like for them?
+
+### Phase 2: Solution Requirements
+- Core features (MVP vs nice-to-have)
+- User workflows and key interactions
+- Data the system needs to handle
+- Integration points with other systems
+- Constraints: budget, timeline, team skills, existing infrastructure
+
+### Phase 3: Technical Architecture
+- System components and how they communicate
+- Data model and storage choices
+- API design (if applicable)
+- Authentication and authorization approach
+- Third-party services and dependencies
+
+### Phase 4: Infrastructure & Operations
+- Hosting environment (cloud provider, on-prem, hybrid)
+- Deployment strategy (containers, serverless, VMs)
+- Scaling considerations
+- Monitoring and observability
+- Backup and disaster recovery
+
+### Phase 5: Security & Compliance
+- Data sensitivity and protection requirements
+- Authentication mechanisms
+- Compliance requirements (GDPR, HIPAA, SOC2, etc.)
+- Threat model considerations
+
+## How to Ask Questions
+
+Ask 2-4 focused questions at a time. For each question:
+- Explain WHY you're asking (what decision it informs)
+- Offer concrete options when helpful, not just open-ended questions
+- Share your initial thinking or recommendation if you have one
+
+Good: "For authentication, are you thinking OAuth (Google/GitHub login) for simplicity,
+or do you need custom username/password? OAuth is faster to implement and more secure,
+but custom auth gives you more control over the user experience."
+
+Bad: "How do you want to handle authentication?"
+
+## Using Web Search
+
+When you have web search available, use it strategically:
+- Research industry best practices for the specific domain
+- Look up current pricing/capabilities of services you might recommend
+- Find examples of similar products for inspiration
+- Verify technical approaches are current (technologies evolve fast)
+- Look for common pitfalls in this type of application
+
+IMPORTANT: Always tell the user when you're searching and summarize what you learned.
+This builds trust and shows you're doing real research, not just making things up.
+
+## Progressive Refinement
+
+As you learn more:
+- Periodically summarize your understanding ("Here's what I have so far...")
+- Explicitly call out assumptions you're making
+- Revisit earlier decisions if new information changes things
+- Be willing to push back if something doesn't make sense
+
+## Re-engagement Support
+
+If the user is returning to continue or update an existing design doc:
+- Acknowledge what exists and ask what they want to change
+- Don't re-ask questions that are already answered in the doc
+- Focus on the delta—what's new, changed, or needs refinement
+
+## Offering to Generate
+
+When you have enough information for a solid design document:
+- Summarize the key decisions that have been made
+- List any important questions that remain unanswered
+- Offer to generate the design doc (the user will click a button)
+
+The user can generate the document at ANY time—it doesn't have to be "complete."
+Better to generate something and iterate than to wait forever for perfection.
+
+## What NOT To Do
+
+- Don't write code or implementation details (that's for later steps)
+- Don't make major assumptions without confirming
+- Don't be a yes-person—challenge ideas that seem problematic
+- Don't overwhelm with too many questions
+- Don't be generic—tailor advice to their specific situation
 </behavior>'''
 
 ARTIFACT_BEHAVIOR = '''<behavior>
@@ -264,6 +348,8 @@ Start your response with <design_doc> immediately.
         self,
         messages: list[dict],
         model: str = "sonnet",
+        tools: Optional[list[str]] = None,
+        timeout: int = 180,
     ) -> AsyncIterator[StreamEvent]:
         """Stream Claude's response to the conversation.
 
@@ -272,6 +358,8 @@ Start your response with <design_doc> immediately.
         Args:
             messages: Conversation history.
             model: Model to use (sonnet, opus, haiku).
+            tools: Optional list of tools to enable (e.g., ['WebSearch', 'WebFetch']).
+            timeout: Timeout in seconds (default 180 for web search).
 
         Yields:
             StreamEvent objects as Claude responds.
@@ -286,8 +374,8 @@ Start your response with <design_doc> immediately.
         async for event in adapter.stream(
             prompt=prompt,
             model=model,
-            tools=None,  # No tools for planning chat
-            timeout=120,
+            tools=tools,
+            timeout=timeout,
         ):
             yield event
 

ralphx/core/preview.py

@@ -337,16 +337,14 @@ class PromptPreviewEngine:
         title = item.get("title") or ""
         metadata = item.get("metadata")
         metadata_json = json.dumps(metadata) if metadata else "{}"
-        namespace = item.get("namespace", "unknown")
+        workflow_id = item.get("workflow_id", "unknown")
 
         # Substitution order: most specific first
         result = template.replace("{{input_item.metadata}}", metadata_json)
         result = result.replace("{{input_item.content}}", content)
         result = result.replace("{{input_item.title}}", title)
         result = result.replace("{{input_item}}", content)
-        result = result.replace("{{namespace}}", namespace)
-        # Backward compatibility
-        result = result.replace("{{source_loop}}", namespace)
+        result = result.replace("{{workflow_id}}", workflow_id)
 
         return result
 
@@ -372,28 +370,17 @@ class PromptPreviewEngine:
             return False
         return bool(self.config.item_types.input.source)
 
-    def _get_source_namespace(self) -> Optional[str]:
-        """Get the source namespace for consumer loops.
-
-        For consumer loops, this is the source loop name used as the namespace.
-        """
-        if not self._is_consumer_loop():
-            return None
-        return self.config.item_types.input.source
-
     def _get_sample_item(self) -> Optional[dict]:
-        """Get a sample item from the source namespace for preview.
+        """Get a sample item for preview (for consumer loops).
 
         Returns:
             Sample item dict or None.
         """
-        namespace = self._get_source_namespace()
-        if not namespace:
+        if not self._is_consumer_loop():
             return None
 
-        # Get first completed item from namespace
+        # Get first completed item
         items, _ = self.db.list_work_items(
-            namespace=namespace,
             status="completed",
             limit=1,
         )
@@ -403,7 +390,6 @@ class PromptPreviewEngine:
 
         # Fallback: get any pending item
         items, _ = self.db.list_work_items(
-            namespace=namespace,
             status="pending",
             limit=1,
         )
@@ -414,8 +400,8 @@ class PromptPreviewEngine:
         # Return a placeholder
         return {
             "id": "sample-001",
-            "content": "[Sample item content - no items in namespace]",
-            "namespace": namespace,
+            "content": "[Sample item content - no items available]",
+            "source": source_name,
         }
 
     def _explain_strategy(self) -> str:
@@ -472,15 +458,13 @@ class PromptPreviewEngine:
                 variables["{{input_item.content}}"] = sample_item.get("content", "")[:50] + "..."
                 variables["{{input_item.title}}"] = sample_item.get("title", "")
                 variables["{{input_item.metadata}}"] = "{...}"
-                variables["{{namespace}}"] = sample_item.get("namespace", "")
-                variables["{{source_loop}}"] = sample_item.get("namespace", "")  # Backward compat
+                variables["{{workflow_id}}"] = sample_item.get("workflow_id", "")
             else:
                 variables["{{input_item}}"] = "[Claimed item content]"
                 variables["{{input_item.content}}"] = "[Claimed item content]"
                 variables["{{input_item.title}}"] = "[Claimed item title]"
                 variables["{{input_item.metadata}}"] = "[Claimed item metadata as JSON]"
-                variables["{{namespace}}"] = self._get_source_namespace() or ""
-                variables["{{source_loop}}"] = self._get_source_namespace() or ""  # Backward compat
+                variables["{{workflow_id}}"] = "[Workflow ID]"
 
         # Design doc variable (if configured)
         if self.config.context and self.config.context.design_doc: