Merge eb6568c8c1 into 3dd37bc94d

Co-authored-by: H Paul Hammann <git@hammann.com>

docs/how-to/monorepo-setup.md

@@ -45,22 +45,25 @@ monorepo-root/
 
 ### Context Injection
 
-Core and BMM workflows automatically check for the existence of `_bmad/.current_project`.
+Core and BMM workflows automatically check for the existence of `{project-root}/_bmad/.current_project`.
 - **If found**: It reads the content (e.g., "app-alpha") and overrides the `output_folder` to `_bmad-output/app-alpha`.
 - **If not found**: It behaves like a standard single-project installation, outputting to `_bmad-output` root.
 
+### The /list-envs Command
+
+You can view all available environments created in your monorepo by running the `/list-envs` command. This will scan your `_bmad-output/` directory and display all existing project environments, as well as indicate which one is currently active.
+
 ### The /set-project Command
 
 You can easily manage the active project context using the `/set-project` workflow.
 
 **To set a context:**
-1. Run `/set-project` in your chat.
-2. Select "Set Project Context".
-3. Enter the name of your project (e.g., `frontend`, `backend`, `mobile-app`).
+1. Run `/set-project <env_name>` in your chat.
+2. If the environment does not exist, you will be prompted to create it interactively.
+3. If you run `/set-project` without an argument, it will automatically list available environments and prompt you to select one or create a new one.
 
 **To clear context (return to single-project mode):**
-1. Run `/set-project`.
-2. Select "Clear Project Context".
+1. Run `/set-project CLEAR`.
 
 ### Inline Override
 

src/bmm/workflows/0-context/list-envs/workflow.md

@@ -0,0 +1,26 @@
+---
+name: list-envs
+description: List available project environments for monorepo support
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# List Project Environments
+
+**Goal:** List the available project context environments for BMAD artifacts.
+
+**Your Role:** Configuration Assistant.
+
+## WORKFLOW ARCHITECTURE
+
+### 1. Identify Environments
+
+- Use your file listing/system capabilities to examine the `{project-root}/_bmad-output/` directory.
+- Identify all subdirectories within this path. Each subdirectory represents an available environment (ignore hidden directories starting with `.`).
+- The root `_bmad-output/` directory itself represents the `default (root)` unset environment.
+
+### 2. Output Results
+
+1. Display a formatted bulleted list of the existing environments you found.
+2. Clearly indicate the `default (root)` environment.
+3. Check if there is an active environment currently set. Read `{project-root}/{{bmadFolderName}}/.current_project`. If it exists, indicate which environment from the list is currently active (e.g. by adding `(ACTIVE)` next to the bullet point).
+4. Inform the user that they can switch to another environment or create a new one using the `/set-project <env_name>` command.

src/bmm/workflows/0-context/set-project/workflow.md

@@ -16,19 +16,39 @@ This is a single-step workflow that updates a local state file.
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 ### 2. Context Management
 
-1.  **Ask User:** "Please enter the **project name** or path relative to `_bmad-output/` (e.g. `project-name` or `libs/auth-lib`). Enter `CLEAR` to reset to root."
-2.  **Wait for Input.**
-3.  **Process Input:**
+1.  **Analyze Request**: Determine the requested project name from the user's initial invocation (e.g., `/set-project my-app`).
+2.  **Wait for Input (If Missing)**: If the user did NOT provide a project name:
+    - Use your file listing capabilities to examine the `{project-root}/_bmad-output/` directory.
+    - Output: A formatted list of the existing environments (subdirectories) you found, explicitly noting the `default (root)` environment.
+    - Ask the user: "Please select an existing environment from the list above, or type a new name to create one. Enter `CLEAR` to reset to root."
+    - **Wait for Input.**
+3.  **Process Input**: Once a project name is established:
     - **Case: CLEAR**:
-      - Delete file: `{project-root}/_bmad/.current_project`
+      - Delete file: `{project-root}/{{bmadFolderName}}/.current_project`
       - Output: "✅ Project context cleared. Artifacts will go to root `_bmad-output/`."
+      - **HALT**
     - **Case: Path Provided**:
-      - **Sanitize:** Remove leading `/` or `_bmad-output/` if present in the input.
-      - Write file: `{project-root}/_bmad/.current_project` with content `<sanitized_path>`
+      - **1. Cleanup**: Remove leading/trailing slashes and any occurrences of `_bmad-output/`.
+      - **2. Validate Existence**: Check if `{project-root}/_bmad-output/<sanitized_path>` exists on the file system.
+        - **If it DOES NOT exist**:
+          - Ask: "The environment `<sanitized_path>` is not present. Do you want to create a new one? (Yes/No)"
+          - **Wait for Input.**
+          - **If No**: Inform the user to run `/list-envs` to see available environments or `/set-project` to try again. **HALT**.
+          - **If Yes**: Proceed to validation.
+      - **3. Validate - No Traversal**: Reject if path contains `..`.
+      - **4. Validate - No Absolute**: Reject if path starts with `/` or drive letter (e.g., `C:`).
+      - **5. Validate - Empty/Whitespace**: Reject if empty or only whitespace.
+      - **6. Validate - Whitelist**: Match against regex `^[a-zA-Z0-9._-/]+$`.
+      - **Check Results**:
+        - **If Invalid**:
+          - Output: "❌ Error: Invalid project context — must be a relative path and contain only alphanumeric characters, dots, dashes, underscores, or slashes. Traversal (..) is strictly forbidden."
+          - **HALT**
+        - **If Valid**:
+          - Write file: `{project-root}/{{bmadFolderName}}/.current_project` with content `<sanitized_path>`
           - Output: "✅ Project context set to: `<sanitized_path>`. Artifacts will go to `_bmad-output/<sanitized_path>/`."
 
 ### 3. Verification
@@ -45,5 +65,5 @@ You can also temporarily run a command against a different project without chang
 
 **Precedence:**
 1. **Inline Override** (`#p:NAME`)
-2. **Global Context File** (`_bmad/.current_project`)
+2. **Global Context File** (`{project-root}/_bmad/.current_project`)
 3. **Default Config** (if neither is present)

src/bmm/workflows/1-analysis/create-product-brief/workflow.md

@@ -49,7 +49,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`, `communication_language`, `document_output_language`, `user_skill_level`
 

src/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md

@@ -373,6 +373,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
 - Complete the domain research workflow
@@ -380,7 +381,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive research document using the full structure above.
+When user selects 'C', append the complete comprehensive research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md

@@ -389,13 +389,14 @@ _This comprehensive market research document serves as an authoritative market r
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the final content to the research document
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
 - Complete the market research workflow
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to the research document using the structure from step 4.
+When user selects 'C', append the content directly to the research document using the structure from step 4. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md

@@ -416,6 +416,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete technical document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
 - Complete the technical research workflow
@@ -423,7 +424,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive technical research document using the full structure above.
+When user selects 'C', append the complete comprehensive technical research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/workflow-domain-research.md

@@ -18,7 +18,7 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`

src/bmm/workflows/1-analysis/research/workflow-market-research.md

@@ -18,7 +18,7 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`

src/bmm/workflows/1-analysis/research/workflow-technical-research.md

@@ -18,7 +18,7 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`

src/bmm/workflows/2-plan-workflows/create-prd/workflow-edit-prd.md

@@ -48,7 +48,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`

src/bmm/workflows/2-plan-workflows/create-prd/workflow-validate-prd.md

@@ -48,7 +48,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`

src/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md

@@ -24,7 +24,7 @@ This uses **micro-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`

src/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md

@@ -44,7 +44,7 @@ description: 'Critical validation workflow that assesses PRD, Architecture, and
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`, `communication_language`, `document_output_language`
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

src/bmm/workflows/3-solutioning/create-architecture/workflow.md

@@ -27,7 +27,7 @@ This uses **micro-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 

src/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md

@@ -48,7 +48,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`, `communication_language`, `document_output_language`

src/bmm/workflows/4-implementation/code-review/instructions.xml

@@ -18,14 +18,15 @@
   <step n="1" goal="Load story and discover changes">
     <check if="{project-root}/_bmad/.current_project exists">
       <action>Read content as project_suffix</action>
-      <!-- Sanitization and Validation -->
-      <action>Trim whitespace and newlines from project_suffix</action>
-      <check if="project_suffix contains '..' or starts with '/' or starts with '\'">
-         <output>🚫 Security Error: Invalid project context path detected.</output>
+      <!-- Security: Reject traversal, absolute paths, and invalid patterns -->
+      <check if="project_suffix is empty OR project_suffix contains '..' or starts with '/' or starts with '\'">
+        <output>🚫 Security Error: Invalid project context path detected — path traversal or absolute path detected.</output>
         <action>HALT</action>
       </check>
-      <check if="project_suffix matches regex '[^a-zA-Z0-9._-]|^\s*$'">
-         <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, or underscores.</output>
+      
+      <!-- Whitelist: Alphanumeric, dots, dashes, underscores, AND slashes (for nested segments) -->
+      <check if="project_suffix matches regex '[^a-zA-Z0-9._-/]|^\s*$'">
+         <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, underscores, or slashes.</output>
          <action>HALT</action>
       </check>
       <action>Override output_folder to {project-root}/_bmad-output/{project_suffix}</action>

src/bmm/workflows/4-implementation/create-story/instructions.xml

@@ -262,7 +262,7 @@
     <critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>
 
     <!-- Recompute output file path with correct output_folder and story_key -->
-    <action>Set {target_story_file} = {output_folder}/{story_key}.md</action>
+    <action>Set {target_story_file} = {output_folder}/{{story_key}}.md</action>
     <action>Output "Generating story file at: {target_story_file}"</action>
 
     <action>Initialize from template.md:

src/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -25,17 +25,26 @@
 </step>
 
 <step n="1" goal="Locate sprint status file">
+  <!-- Runtime Validation Gate -->
+  <check if="{sprint_status_file} is not defined OR {sprint_status_file} == ''">
+    <output>🚫 Error: Workflow configuration not loaded properly ({sprint_status_file} is undefined).</output>
+    <action>HALT</action>
+  </check>
+
   <action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
   <action>Try {sprint_status_file}</action>
   <check if="file not found">
-    <output>❌ sprint-status.yaml not found.
+    <output>❌ sprint-status.yaml not found at: {sprint_status_file}
 Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-status.</output>
-    <action>Exit workflow</action>
+    <action>HALT</action>
   </check>
   <action>Continue to Step 2</action>
 </step>
 
 <step n="2" goal="Read and parse sprint-status.yaml">
+  <check if="{sprint_status_file} is not defined">
+    <action>HALT - Safety Error: sprint_status_file variable lost or undefined.</action>
+  </check>
   <action>Read the FULL file: {sprint_status_file}</action>
   <action>Parse fields: generated, project, project_key, tracking_system, story_location</action>
   <action>Parse development_status map. Classify keys:</action>
@@ -165,6 +174,9 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
 <!-- ========================= -->
 
 <step n="20" goal="Data mode output">
+  <check if="{sprint_status_file} is not defined">
+    <action>HALT - Safety Error: sprint_status_file variable lost or undefined.</action>
+  </check>
   <action>Load and parse {sprint_status_file} same as Step 2</action>
   <action>Compute recommendation same as Step 3</action>
   <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
@@ -186,6 +198,9 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
 <!-- ========================= -->
 
 <step n="30" goal="Validate sprint-status file">
+  <check if="{sprint_status_file} is not defined">
+    <action>HALT - Safety Error: sprint_status_file variable lost or undefined.</action>
+  </check>
   <action>Check that {sprint_status_file} exists</action>
   <check if="missing">
     <template-output>is_valid = false</template-output>

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -25,7 +25,7 @@ This uses **step-file architecture** for focused execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -66,7 +66,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`

src/bmm/workflows/document-project/instructions.md

@@ -81,7 +81,7 @@
 
 ## 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 <step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">

src/bmm/workflows/document-project/workflows/deep-dive-instructions.md

@@ -11,18 +11,31 @@
 <action>Load existing project structure from index.md and project-parts.json (if exists)</action>
 <action>Load source tree analysis to understand available areas</action>
 
-<check if="{project-root}/_bmad/.current_project exists">
+<!-- Step 1: Check for inline project override (#project:NAME or #p:NAME) -->
+<action>Scan request for pattern #project:NAME or #p:NAME (case-insensitive)</action>
+<check if="inline override found">
+  <action>Set project_suffix = extracted NAME</action>
+</check>
+
+<!-- Step 2: Fall back to .current_project file -->
+<check if="project_suffix not yet set AND {project-root}/_bmad/.current_project exists">
   <action>Read content as project_suffix</action>
-  <!-- Sanitization and Validation -->
-  <action>Trim whitespace and newlines from project_suffix</action>
-  <check if="project_suffix contains '..' or starts with '/' or starts with '\'">
-      <output>🚫 Security Error: Invalid project context path detected.</output>
+</check>
+
+<!-- Step 3: Validate and Canonicalize -->
+<check if="project_suffix is set">
+  <!-- Security: Reject traversal, absolute paths, and invalid patterns -->
+  <check if="project_suffix is empty OR project_suffix contains '..' or starts with '/' or starts with '\'">
+    <output>🚫 Security Error: Invalid project context path detected — path traversal or absolute path detected.</output>
     <action>HALT</action>
   </check>
-  <check if="project_suffix matches regex '[^a-zA-Z0-9._-]|^\s*$'">
-      <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, or underscores.</output>
+  
+  <!-- Whitelist: Alphanumeric, dots, dashes, underscores, AND slashes (for nested segments) -->
+  <check if="project_suffix matches regex '[^a-zA-Z0-9._-/]|^\s*$'">
+     <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, underscores, or slashes.</output>
      <action>HALT</action>
   </check>
+
   <action>Override output_folder to {project-root}/_bmad-output/{project_suffix}</action>
   <action>Override project_knowledge to {project-root}/_bmad-output/{project_suffix}</action>
   <action>Output "Monorepo context detected. Writing deep-dive artifacts to: {project_knowledge}"</action>
@@ -269,7 +282,7 @@ Detailed exhaustive analysis of specific areas:
 - Dependency graph and data flow
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - Related code and reuse opportunities

src/bmm/workflows/generate-project-context/workflow.md

@@ -27,7 +27,7 @@ This uses **micro-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `user_name`

src/core/workflows/advanced-elicitation/workflow.xml

@@ -21,19 +21,38 @@
   <flow>
     <step n="1" title="Method Registry Loading">
       <!-- Retained inline check because this workflow may be invoked as a standalone tool mid-conversation, bypassing the OS-level context injection. -->
-      <check if="{project-root}/_bmad/.current_project exists">
+      
+      <!-- Step 1: Check for inline project override (#project:NAME or #p:NAME) -->
+      <action>Scan request for pattern #project:NAME or #p:NAME (case-insensitive)</action>
+      <check if="inline override found">
+        <action>Set project_suffix = extracted NAME</action>
+      </check>
+
+      <!-- Step 2: Fall back to .current_project file -->
+      <check if="project_suffix not yet set AND {project-root}/_bmad/.current_project exists">
         <action>Read content as project_suffix</action>
-        <!-- Sanitization and Validation -->
-        <action>Trim whitespace and newlines from project_suffix</action>
-        <check if="project_suffix contains '..' or starts with '/' or starts with '\'">
-           <output>🚫 Security Error: Invalid project context path detected.</output>
+      </check>
+
+      <!-- Step 3: Validate and Canonicalize -->
+      <check if="project_suffix is set">
+        <!-- Security: Reject traversal, absolute paths, and invalid patterns -->
+        <check if="project_suffix is empty OR project_suffix contains '..' or starts with '/' or starts with '\'">
+           <output>🚫 Security Error: Invalid project context path detected — path traversal or absolute path detected.</output>
            <action>HALT</action>
         </check>
-        <check if="project_suffix matches regex '[^a-zA-Z0-9._-]|^\s*$'">
-           <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, or underscores.</output>
+        
+        <!-- Whitelist: Alphanumeric, dots, dashes, underscores, AND slashes (for nested segments) -->
+        <check if="project_suffix matches regex '[^a-zA-Z0-9._-/]|^\s*$'">
+           <output>🚫 Error: Project context must only contain alphanumeric characters, dots, dashes, underscores, or slashes.</output>
            <action>HALT</action>
         </check>
+
         <action>Override output_folder to {project-root}/_bmad-output/{project_suffix}</action>
+        <action>Override planning_artifacts to {project-root}/_bmad-output/{project_suffix}</action>
+        <action>Override implementation_artifacts to {project-root}/_bmad-output/{project_suffix}</action>
+        <action>Override project_knowledge to {project-root}/_bmad-output/{project_suffix}</action>
+        <action>Override sprint_status_file to {project-root}/_bmad-output/{project_suffix}/sprint-status.yaml</action>
+        <action>Output "Monorepo context detected. Paths adjusted to: {project_suffix}"</action>
       </check>
 
       <action>Load and read {{methods}} and {{agent-party}}</action>

src/core/workflows/brainstorming/workflow.md

@@ -34,7 +34,7 @@ This uses **micro-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 
 - `project_name`, `output_folder`, `user_name`

src/core/workflows/party-mode/workflow.md

@@ -27,7 +27,7 @@ This uses **micro-file architecture** with **sequential conversation orchestrati
 
 ### 1. Configuration Loading
 
-Load and read full config from {main_config} and resolve basic variables.
+Load and read full config from {main_config} and resolve variables and artifact paths.
 
 - `project_name`, `output_folder`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`

test/test-context-logic-integration.js

@@ -108,9 +108,13 @@ async function runTests() {
 
   for (const { file, expectedImport } of consumers) {
     const fullPath = path.join(root, file);
+    try {
       const content = await readFile(fullPath);
       ok(content.includes(expectedImport), `${path.basename(file)} imports context-logic correctly`);
       ok(content.includes("replaceAll('{{monorepo_context_logic}}'"), `${path.basename(file)} uses replaceAll for placeholder`);
+    } catch (error) {
+      ok(false, `File not found or unreadable: ${fullPath} - ${error.message}`);
+    }
   }
   console.log('');
 
@@ -135,10 +139,14 @@ async function runTests() {
 
   for (const filePath of mustHavePlaceholder) {
     const rel = path.relative(root, filePath);
+    try {
       const content = await readFile(filePath);
       ok(content.includes('{{monorepo_context_logic}}'), `${path.basename(filePath)} has {{monorepo_context_logic}} placeholder`);
       // Must NOT have raw hardcoded block (only the shared module should have it)
       ok(!content.includes('<monorepo-context-check'), `${path.basename(filePath)} has NO hardcoded <monorepo-context-check> block`);
+    } catch (error) {
+      ok(false, `File not found or unreadable: ${filePath} - ${error.message}`);
+    }
   }
   console.log('');
 

test/test-monorepo-validation.js

@@ -18,7 +18,7 @@
 
 const fs = require('fs-extra');
 const path = require('node:path');
-const glob = require('glob');
+const { globSync } = require('glob');
 
 // ANSI colors
 const colors = {
@@ -70,15 +70,26 @@ async function runTests() {
   console.log(`${colors.yellow}Test Suite 2: No Stale Inline Monorepo Context Checks${colors.reset}\n`);
   console.log(`  ${colors.dim}(Inline checks were moved to workflow.xml via context-logic.js)${colors.reset}\n`);
 
-  const workflowFiles = glob.sync('src/{core,bmm}/workflows/**/*.{md,xml}', { cwd: projectRoot });
+  const workflowFiles = globSync('src/{core,bmm}/workflows/**/*.{md,xml}', { cwd: projectRoot });
+
+  const exceptions = [
+    'context-logic.js',
+    'code-review/instructions.xml',
+    'create-story/instructions.xml',
+    'dev-story/instructions.xml',
+    'advanced-elicitation/workflow.xml',
+    'deep-dive-instructions.md',
+  ];
 
   for (const file of workflowFiles) {
-    // skip the context-logic source itself (it's the canonical source)
-    if (file.includes('context-logic')) continue;
+    if (exceptions.some((e) => file.endsWith(e))) continue;
 
     const content = await fs.readFile(path.join(projectRoot, file), 'utf8');
 
-    assert(!content.includes('**Monorepo Context Check:**'), `No stale inline check block in: ${file}`);
+    const hasMarkdownCheck = content.includes('**Monorepo Context Check:**');
+    const hasXmlCheck = /<check\s+if=.*_bmad\/\.current_project.*/.test(content);
+
+    assert(!hasMarkdownCheck && !hasXmlCheck, `No stale inline check block in: ${file}`);
   }
 
   console.log('');
@@ -104,8 +115,9 @@ async function runTests() {
     assert(exists, 'set-project workflow file exists');
     if (exists) {
       const content = await fs.readFile(setProjectPath, 'utf8');
-      assert(content.includes('_bmad/.current_project'), 'set-project implementation manages .current_project');
-      assert(content.includes('my-app'), 'set-project examples use generic public-friendly names');
+      assert(content.includes('{{bmadFolderName}}/.current_project'), 'set-project implementation manages .current_project');
+      const examplePattern = /(?:example|my[-_ ]?app|[a-z0-9]+-[a-z0-9]+)/i;
+      assert(examplePattern.test(content), 'set-project examples use generic public-friendly names');
     }
   } catch (error) {
     assert(false, 'set-project check failed', error.message);

tools/cli/installers/lib/core/installer.js

@@ -90,9 +90,16 @@ class Installer {
         // Read the file content
         let content = await fs.readFile(sourcePath, 'utf8');
 
-        // Apply replacements
+        // Apply replacements in an order that protects _bmad-output literals.
+        // 1. First, inject the monorepo logic (which now uses {{bmadFolderName}} for its config dir references).
         content = content.replaceAll('{{monorepo_context_logic}}', MONOREPO_CONTEXT_LOGIC);
-        content = content.replaceAll('_bmad', this.bmadFolderName);
+
+        // 2. Perform a precise replacement of the generic '_bmad' folder name using a negative lookahead
+        //    to avoid corrupting the fixed '_bmad-output' folder name.
+        content = content.replaceAll(/_bmad(?!-output)/g, this.bmadFolderName);
+
+        // 3. Finally, resolve the explicit placeholder used in centralized context logic.
+        content = content.replaceAll('{{bmadFolderName}}', this.bmadFolderName);
 
         // Write to target with replaced content
         await fs.ensureDir(path.dirname(targetPath));

tools/cli/installers/lib/ide/_config-driven.js

@@ -401,10 +401,11 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
       .replaceAll('{{workflow_path}}', pathToUse)
       .replaceAll('{{monorepo_context_logic}}', MONOREPO_CONTEXT_LOGIC);
 
-    // Replace _bmad placeholder with actual folder name
-    rendered = rendered.replaceAll('_bmad', this.bmadFolderName);
+    // Replace _bmad placeholder with actual folder name using precise regex
+    // This protects literals like '_bmad-output' from corruption.
+    rendered = rendered.replaceAll(/_bmad(?!-output)/g, this.bmadFolderName);
 
-    // Replace {{bmadFolderName}} placeholder if present
+    // Replace {{bmadFolderName}} placeholder (used in centralized context logic)
     rendered = rendered.replaceAll('{{bmadFolderName}}', this.bmadFolderName);
 
     return rendered;

tools/cli/installers/lib/ide/shared/context-logic.js

@@ -17,20 +17,22 @@ const MONOREPO_CONTEXT_LOGIC = `
   </check>
 
   <!-- Step 2: Fall back to .current_project file -->
-  <check if="project_suffix not yet set AND {project-root}/_bmad/.current_project exists">
-    <action>Read {project-root}/_bmad/.current_project as project_suffix</action>
+  <check if="project_suffix not yet set AND {project-root}/{{bmadFolderName}}/.current_project exists">
+    <action>Read {project-root}/{{bmadFolderName}}/.current_project as project_suffix</action>
   </check>
 
   <!-- Step 3: Validate -->
   <check if="project_suffix is set">
     <action>Trim whitespace and newlines from project_suffix</action>
-    <!-- Security: Prevent path traversal and invalid chars -->
-    <check if="project_suffix contains '..' OR starts with '/' OR starts with '\\'">
-      <output>🚫 Security Error: Invalid project context — path traversal detected.</output>
+    <!-- Security: Reject traversal, absolute paths, and invalid patterns -->
+    <check if="project_suffix is empty OR project_suffix contains '..' OR starts with '/' OR starts with '\\\\'">
+      <output>🚫 Security Error: Invalid project context — path traversal or absolute path detected.</output>
       <action>HALT</action>
     </check>
-    <check if="project_suffix matching regex [^a-zA-Z0-9._-]">
-      <output>🚫 Error: project_suffix must only contain alphanumeric characters, dots, dashes, or underscores.</output>
+    
+    <!-- Whitelist: Alphanumeric, dots, dashes, underscores, AND slashes (for nested segments) -->
+    <check if="project_suffix matches regex '[^a-zA-Z0-9._-/]|^\\\\s*$'">
+      <output>🚫 Error: project_suffix must only contain alphanumeric characters, dots, dashes, underscores, or slashes.</output>
       <action>HALT</action>
     </check>
 

tools/cli/installers/lib/ide/shared/workflow-command-generator.js

@@ -154,13 +154,19 @@ class WorkflowCommandGenerator {
     const { MONOREPO_CONTEXT_LOGIC } = require('./context-logic');
 
     // Replace template variables
-    return template
+    return (
+      template
         .replaceAll('{{name}}', workflow.name)
         .replaceAll('{{module}}', workflow.module)
         .replaceAll('{{description}}', workflow.description)
         .replaceAll('{{workflow_path}}', workflowPath)
         .replaceAll('{{monorepo_context_logic}}', MONOREPO_CONTEXT_LOGIC)
-      .replaceAll('_bmad', this.bmadFolderName);
+        // Replace _bmad placeholder with actual folder name using precise regex
+        // This protects literals like '_bmad-output' from corruption.
+        .replaceAll(/_bmad(?!-output)/g, this.bmadFolderName)
+        // Replace {{bmadFolderName}} placeholder (used in centralized context logic)
+        .replaceAll('{{bmadFolderName}}', this.bmadFolderName)
+    );
   }
 
   /**

tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md

@@ -6,9 +6,9 @@ disable-model-invocation: true
 
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
 
-<steps CRITICAL="TRUE">
-0. {{monorepo_context_logic}}
+{{monorepo_context_logic}}
 
+<steps CRITICAL="TRUE">
 1. Always LOAD the FULL @{project-root}/{{bmadFolderName}}/core/tasks/workflow.xml
 2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{project-root}/{{bmadFolderName}}/{{path}}
 3. Pass the yaml path @{project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions

tools/cli/installers/lib/ide/templates/combined/kiro-workflow.md

@@ -6,4 +6,4 @@ inclusion: manual
 
 {{monorepo_context_logic}}
 
-IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL #[[file:{{bmadFolderName}}/{{path}}]], READ its entire contents and follow its directions exactly!

tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md

@@ -3,12 +3,13 @@ name: '{{name}}'
 description: '{{description}}'
 ---
 
+{{monorepo_context_logic}}
+
 Execute the BMAD '{{name}}' workflow.
 
 CRITICAL: You must load and follow the workflow definition exactly.
 
 WORKFLOW INSTRUCTIONS:
-{{monorepo_context_logic}}
 
 1. LOAD the workflow file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents