bmad-fh 6.0.0-alpha.23.66f19588 → 6.0.0-alpha.23.6874ced1

package/docs/plans/multi-scope-parallel-artifacts-plan.md

@@ -1,3 +1,8 @@
+---
+title: 'Multi-Scope Parallel Artifacts System - Implementation Plan'
+description: 'Implementation plan for the multi-scope parallel artifact system'
+---
+
 # Multi-Scope Parallel Artifacts System - Implementation Plan
 
 > **Status:** Planning Complete  
@@ -35,18 +40,18 @@ This plan outlines the implementation of a **multi-scope parallel artifact syste
 
 ## Key Design Decisions
 
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| **Sprint-status handling** | Per-scope | Each scope has independent sprint planning, no parallel conflicts |
-| **Project-context location** | Both (global + per-scope) | Global "bible" in `_shared/`, optional scope-specific that extends |
-| **Scope vs Module** | Different concepts | Module = code organization (bmm/core), Scope = artifact isolation (auth/payments) |
-| **Cross-scope access** | Read any, write own | Liberal reads for dependency awareness, strict writes for isolation |
-| **Test directories** | Scoped | `{output_folder}/{scope}/tests` for full isolation |
-| **Workflow updates** | Automated script | Handle 22+ workflow.yaml files programmatically |
-| **File locking** | proper-lockfile npm | Battle-tested, cross-platform locking |
-| **Git hooks** | This repo only | For contributor workflow, NOT installed with bmad |
-| **Migration strategy** | Auto-migrate to 'default' | Existing artifacts move to default scope automatically |
-| **Scope ID format** | Strict | Lowercase alphanumeric + hyphens only |
+| Decision                     | Choice                    | Rationale                                                                         |
+| ---------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
+| **Sprint-status handling**   | Per-scope                 | Each scope has independent sprint planning, no parallel conflicts                 |
+| **Project-context location** | Both (global + per-scope) | Global "bible" in `_shared/`, optional scope-specific that extends                |
+| **Scope vs Module**          | Different concepts        | Module = code organization (bmm/core), Scope = artifact isolation (auth/payments) |
+| **Cross-scope access**       | Read any, write own       | Liberal reads for dependency awareness, strict writes for isolation               |
+| **Test directories**         | Scoped                    | `{output_folder}/{scope}/tests` for full isolation                                |
+| **Workflow updates**         | Automated script          | Handle 22+ workflow.yaml files programmatically                                   |
+| **File locking**             | proper-lockfile npm       | Battle-tested, cross-platform locking                                             |
+| **Git hooks**                | This repo only            | For contributor workflow, NOT installed with bmad                                 |
+| **Migration strategy**       | Auto-migrate to 'default' | Existing artifacts move to default scope automatically                            |
+| **Scope ID format**          | Strict                    | Lowercase alphanumeric + hyphens only                                             |
 
 ---
 
@@ -173,25 +178,26 @@ git remote add upstream git@github.com:bmad-code-org/BMAD-METHOD.git
 version: 1
 
 settings:
-  allow_adhoc_scopes: true        # Allow on-demand scope creation
-  isolation_mode: strict          # strict | warn | permissive
-  default_output_base: "_bmad-output"
-  default_shared_path: "_bmad-output/_shared"
+  allow_adhoc_scopes: true # Allow on-demand scope creation
+  isolation_mode: strict # strict | warn | permissive
+  default_output_base: '_bmad-output'
+  default_shared_path: '_bmad-output/_shared'
 
 scopes:
   auth:
-    id: "auth"
-    name: "Authentication Service"
-    description: "User authentication, SSO, authorization"
-    status: active                # active | archived
-    dependencies: []              # Scopes this depends on
-    created: "2026-01-21T10:00:00Z"
+    id: 'auth'
+    name: 'Authentication Service'
+    description: 'User authentication, SSO, authorization'
+    status: active # active | archived
+    dependencies: [] # Scopes this depends on
+    created: '2026-01-21T10:00:00Z'
     _meta:
-      last_activity: "2026-01-21T15:30:00Z"
+      last_activity: '2026-01-21T15:30:00Z'
       artifact_count: 12
 ```
 
 **Validation Rules:**
+
 - Scope ID: `^[a-z][a-z0-9-]*[a-z0-9]$` (2-50 chars)
 - Reserved IDs: `_shared`, `_events`, `_config`, `global`
 - Circular dependency detection required
@@ -208,15 +214,15 @@ class ScopeManager {
   async createScope(scopeId, options)
   async updateScope(scopeId, updates)
   async removeScope(scopeId, options)
-  
+
   // Path Resolution
   async getScopePaths(scopeId)
   resolvePath(template, scopeId)
-  
+
   // Validation
   validateScopeId(scopeId)
   validateDependencies(scopeId, dependencies, allScopes)
-  
+
   // Dependencies
   async getDependencyTree(scopeId)
   findDependentScopes(scopeId, allScopes)
@@ -227,19 +233,20 @@ class ScopeManager {
 
 **File:** `tools/cli/commands/scope.js`
 
-| Command | Description |
-|---------|-------------|
-| `bmad scope list` | List all scopes |
-| `bmad scope create <id>` | Create new scope interactively |
-| `bmad scope info <id>` | Show scope details |
-| `bmad scope remove <id>` | Remove scope |
-| `bmad scope migrate` | Migrate existing to scoped structure |
+| Command                  | Description                          |
+| ------------------------ | ------------------------------------ |
+| `bmad scope list`        | List all scopes                      |
+| `bmad scope create <id>` | Create new scope interactively       |
+| `bmad scope info <id>`   | Show scope details                   |
+| `bmad scope remove <id>` | Remove scope                         |
+| `bmad scope migrate`     | Migrate existing to scoped structure |
 
 ### 1.4 Directory Structure Generator
 
 **File:** `src/core/scope/scope-initializer.js`
 
 Creates on scope creation:
+
 ```
 _bmad-output/{scope}/
 ├── planning-artifacts/
@@ -249,6 +256,7 @@ _bmad-output/{scope}/
 ```
 
 Creates on first scope (one-time):
+
 ```
 _bmad-output/_shared/
 ├── project-context.md      # Global project context template
@@ -265,6 +273,7 @@ _bmad/_events/
 **File:** `src/core/scope/scope-migrator.js`
 
 Steps:
+
 1. Create backup of `_bmad-output/`
 2. Initialize scope system
 3. Create `default` scope
@@ -290,14 +299,14 @@ Add Step 0 before existing Step 1:
     <action>Scan workflow.yaml for {scope} variable</action>
     <action>If found → workflow requires scope</action>
   </substep>
-  
+
   <substep n="0b" title="Resolve Scope">
     <!-- Priority order: -->
     <!-- 1. --scope argument from command -->
     <!-- 2. Session context (if set) -->
     <!-- 3. Prompt user to select/create -->
   </substep>
-  
+
   <substep n="0c" title="Load Scope Context">
     <action>Load scope config from scopes.yaml</action>
     <action>Resolve scope paths</action>
@@ -333,6 +342,7 @@ implementation_artifacts:
 **File:** `tools/cli/scripts/migrate-workflows.js`
 
 Updates for 22+ workflow files:
+
 1. Update `test_dir` variables to use `{output_folder}/{scope}/tests`
 2. Handle variations in path definitions
 3. Preserve `{config_source}:` references (they'll work via updated module.yaml)
@@ -357,6 +367,7 @@ Updates for 22+ workflow files:
 **Modification to workflow.xml:**
 
 When `<invoke-workflow>` is encountered:
+
 1. Pass current `{scope}` as implicit parameter
 2. Child workflow inherits scope from parent
 3. Can be overridden with explicit `<param>scope: other</param>`
@@ -377,27 +388,27 @@ class ArtifactResolver {
     this.currentScope = currentScope;
     this.basePath = basePath;
   }
-  
+
   // Read-any: Allow reading from any scope
   canRead(path) {
     return true; // All reads allowed
   }
-  
+
   // Write-own: Only allow writing to current scope
   canWrite(path) {
     const targetScope = this.extractScopeFromPath(path);
-    
+
     if (targetScope === '_shared') {
       throw new Error('Cannot write directly to _shared. Use: bmad scope sync-up');
     }
-    
+
     if (targetScope !== this.currentScope) {
       throw new Error(`Cannot write to scope '${targetScope}' while in scope '${this.currentScope}'`);
     }
-    
+
     return true;
   }
-  
+
   extractScopeFromPath(path) {
     // Extract scope from path like _bmad-output/auth/...
   }
@@ -414,27 +425,27 @@ const lockfile = require('proper-lockfile');
 class StateLock {
   async withLock(filePath, operation) {
     const release = await lockfile.lock(filePath, {
-      stale: 30000,      // 30s stale timeout
-      retries: { retries: 10, minTimeout: 100, maxTimeout: 1000 }
+      stale: 30000, // 30s stale timeout
+      retries: { retries: 10, minTimeout: 100, maxTimeout: 1000 },
     });
-    
+
     try {
       return await operation();
     } finally {
       await release();
     }
   }
-  
+
   // Optimistic locking with version field
   async updateYamlWithVersion(filePath, modifier) {
     return this.withLock(filePath, async () => {
       const data = await this.readYaml(filePath);
       const currentVersion = data._version || 0;
-      
+
       const modified = await modifier(data);
       modified._version = currentVersion + 1;
       modified._lastModified = new Date().toISOString();
-      
+
       await this.writeYaml(filePath, modified);
       return modified;
     });
@@ -443,6 +454,7 @@ class StateLock {
 ```
 
 **Files requiring locking:**
+
 - `{scope}/implementation-artifacts/sprint-status.yaml`
 - `{scope}/planning-artifacts/bmm-workflow-status.yaml`
 - `_shared/` files during sync operations
@@ -451,6 +463,7 @@ class StateLock {
 ### 3.3 Package.json Update
 
 Add dependency:
+
 ```json
 {
   "dependencies": {
@@ -470,16 +483,18 @@ Add dependency:
 **Command:** `bmad scope sync-up <scope>`
 
 **Logic:**
+
 1. Identify promotable artifacts (configurable patterns)
 2. Check for conflicts with existing shared files
 3. Copy to `_shared/` with attribution metadata
 4. Log event for dependent scope notification
 
 **Metadata added to promoted files:**
+
 ```yaml
 # _shared/architecture/auth-api.md.meta
 source_scope: auth
-promoted_at: "2026-01-21T10:00:00Z"
+promoted_at: '2026-01-21T10:00:00Z'
 original_hash: abc123
 version: 1
 ```
@@ -489,6 +504,7 @@ version: 1
 **Command:** `bmad scope sync-down <scope>`
 
 **Logic:**
+
 1. Find shared updates since last sync
 2. Compare with local copies (if any)
 3. Handle conflicts (prompt user for resolution)
@@ -498,6 +514,7 @@ version: 1
 ### 4.3 Conflict Resolution
 
 **Options when conflict detected:**
+
 1. Keep local (overwrite shared)
 2. Keep shared (discard local)
 3. Merge (3-way diff if possible)
@@ -520,14 +537,14 @@ events:
     type: artifact_created
     scope: auth
     artifact: planning-artifacts/prd.md
-    timestamp: "2026-01-21T10:30:00Z"
-    
+    timestamp: '2026-01-21T10:30:00Z'
+
   - id: evt_002
     type: artifact_promoted
     scope: auth
     artifact: architecture.md
     shared_path: _shared/auth/architecture.md
-    timestamp: "2026-01-21T11:00:00Z"
+    timestamp: '2026-01-21T11:00:00Z'
 ```
 
 ### 5.2 Subscriptions
@@ -539,13 +556,14 @@ subscriptions:
   payments:
     watch:
       - scope: auth
-        patterns: ["contracts/*", "architecture.md"]
+        patterns: ['contracts/*', 'architecture.md']
     notify: true
 ```
 
 ### 5.3 Notification on Activation
 
 When agent/workflow activates with scope:
+
 1. Check subscriptions for this scope
 2. Find events since last activity
 3. Display pending updates (if any)
@@ -562,6 +580,7 @@ When agent/workflow activates with scope:
 **File:** `tools/cli/installers/lib/ide/shared/scope-aware-command.js`
 
 Updates to workflow-command-template.md:
+
 ```markdown
 ### Scope Resolution
 
@@ -581,22 +600,24 @@ Store selected scope for session.
 ```yaml
 # .bmad-scope (gitignored)
 active_scope: auth
-set_at: "2026-01-21T10:00:00Z"
+set_at: '2026-01-21T10:00:00Z'
 ```
 
 ### 6.3 Agent Menu Updates
 
 Add `scope_required` attribute:
+
 ```yaml
 menu:
-  - trigger: "prd"
-    workflow: "..."
-    scope_required: true  # Enforce scope for this menu item
+  - trigger: 'prd'
+    workflow: '...'
+    scope_required: true # Enforce scope for this menu item
 ```
 
 ### 6.4 Documentation
 
 Files to create:
+
 1. `docs/multi-scope-guide.md` - User guide
 2. `docs/migration-guide.md` - Upgrading existing installations
 3. Update README with multi-scope overview
@@ -605,14 +626,14 @@ Files to create:
 
 ## Risk Mitigation
 
-| Risk | Mitigation |
-|------|------------|
-| Breaking existing installations | Auto-migration with backup, rollback capability |
-| Parallel write conflicts | File locking + optimistic versioning |
-| Cross-scope data corruption | Write isolation enforcement in ArtifactResolver |
-| Complex merge conflicts | Clear conflict resolution UI + skip option |
-| IDE compatibility | Test with all supported IDEs, graceful fallbacks |
-| Performance with many scopes | Lazy loading, scope caching |
+| Risk                            | Mitigation                                       |
+| ------------------------------- | ------------------------------------------------ |
+| Breaking existing installations | Auto-migration with backup, rollback capability  |
+| Parallel write conflicts        | File locking + optimistic versioning             |
+| Cross-scope data corruption     | Write isolation enforcement in ArtifactResolver  |
+| Complex merge conflicts         | Clear conflict resolution UI + skip option       |
+| IDE compatibility               | Test with all supported IDEs, graceful fallbacks |
+| Performance with many scopes    | Lazy loading, scope caching                      |
 
 ---
 
@@ -660,36 +681,36 @@ MVP can be achieved with Phases 0-3 (isolation working, no sync/events yet).
 
 ### New Files
 
-| Path | Purpose |
-|------|---------|
-| `.githooks/pre-push` | Git hook for single-commit workflow |
-| `.githooks/pre-commit` | Git hook to block main commits |
-| `.githooks/post-checkout` | Git hook for sync reminders |
-| `src/core/scope/scope-manager.js` | Scope CRUD operations |
-| `src/core/scope/scope-initializer.js` | Directory creation |
-| `src/core/scope/scope-migrator.js` | Migration logic |
-| `src/core/scope/scope-context.js` | Session context |
-| `src/core/scope/artifact-resolver.js` | Read/write enforcement |
-| `src/core/scope/state-lock.js` | File locking utilities |
-| `src/core/scope/scope-sync.js` | Sync-up/down logic |
-| `src/core/scope/event-logger.js` | Event logging |
-| `tools/cli/commands/scope.js` | CLI scope commands |
-| `tools/cli/scripts/migrate-workflows.js` | Workflow update script |
-| `docs/plans/multi-scope-parallel-artifacts-plan.md` | This file |
+| Path                                                | Purpose                             |
+| --------------------------------------------------- | ----------------------------------- |
+| `.githooks/pre-push`                                | Git hook for single-commit workflow |
+| `.githooks/pre-commit`                              | Git hook to block main commits      |
+| `.githooks/post-checkout`                           | Git hook for sync reminders         |
+| `src/core/scope/scope-manager.js`                   | Scope CRUD operations               |
+| `src/core/scope/scope-initializer.js`               | Directory creation                  |
+| `src/core/scope/scope-migrator.js`                  | Migration logic                     |
+| `src/core/scope/scope-context.js`                   | Session context                     |
+| `src/core/scope/artifact-resolver.js`               | Read/write enforcement              |
+| `src/core/scope/state-lock.js`                      | File locking utilities              |
+| `src/core/scope/scope-sync.js`                      | Sync-up/down logic                  |
+| `src/core/scope/event-logger.js`                    | Event logging                       |
+| `tools/cli/commands/scope.js`                       | CLI scope commands                  |
+| `tools/cli/scripts/migrate-workflows.js`            | Workflow update script              |
+| `docs/plans/multi-scope-parallel-artifacts-plan.md` | This file                           |
 
 ### Modified Files
 
-| Path | Changes |
-|------|---------|
-| `src/core/tasks/workflow.xml` | Add Step 0 for scope init |
-| `src/core/module.yaml` | Add scope settings |
-| `src/bmm/module.yaml` | Add {scope} to paths |
-| `src/utility/agent-components/activation-steps.txt` | Add scope loading |
-| `tools/cli/bmad-cli.js` | Register scope command |
-| `tools/cli/installers/lib/ide/templates/*` | Scope-aware templates |
-| `package.json` | Add proper-lockfile dependency |
-| `22+ workflow.yaml files` | Update test_dir paths (via script) |
+| Path                                                | Changes                            |
+| --------------------------------------------------- | ---------------------------------- |
+| `src/core/tasks/workflow.xml`                       | Add Step 0 for scope init          |
+| `src/core/module.yaml`                              | Add scope settings                 |
+| `src/bmm/module.yaml`                               | Add {scope} to paths               |
+| `src/utility/agent-components/activation-steps.txt` | Add scope loading                  |
+| `tools/cli/bmad-cli.js`                             | Register scope command             |
+| `tools/cli/installers/lib/ide/templates/*`          | Scope-aware templates              |
+| `package.json`                                      | Add proper-lockfile dependency     |
+| `22+ workflow.yaml files`                           | Update test_dir paths (via script) |
 
 ---
 
-*End of Plan*
+_End of Plan_

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-fh",
-  "version": "6.0.0-alpha.23.66f19588",
+  "version": "6.0.0-alpha.23.6874ced1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -44,7 +44,8 @@
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
-    "test": "npm run test:schemas && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:install && npm run test:cli-args && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:cli-args": "node test/test-cli-arguments.js",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
     "test:schemas": "node test/test-agent-schema.js",

package/src/core/lib/scope/scope-context.js

@@ -163,9 +163,11 @@ class ScopeContext {
    * Priority: explicit > session > environment > prompt
    * @param {string} explicitScope - Explicitly provided scope (highest priority)
    * @param {boolean} promptIfMissing - Whether to throw if no scope found
+   * @param {object} options - Additional options
+   * @param {boolean} options.silent - Suppress warning when no scope found
    * @returns {Promise<string|null>} Resolved scope ID
    */
-  async resolveScope(explicitScope = null, promptIfMissing = false) {
+  async resolveScope(explicitScope = null, promptIfMissing = false, options = {}) {
     // 1. Explicit scope (from --scope flag or parameter)
     if (explicitScope) {
       return explicitScope;
@@ -185,7 +187,16 @@ class ScopeContext {
 
     // 4. No scope found
     if (promptIfMissing) {
-      throw new Error('No scope set. Use --scope flag or run: bmad scope create <id>');
+      throw new Error('No scope set. Use --scope flag or run: npx bmad-fh scope set <id>');
+    }
+
+    // Warn user about missing scope (unless silent mode)
+    if (!options.silent) {
+      console.warn(
+        '\u001B[33mNo scope set. Artifacts will go to root _bmad-output/ directory.\u001B[0m\n' +
+          '   To use scoped artifacts, run: npx bmad-fh scope set <scope-id>\n' +
+          '   Or set BMAD_SCOPE environment variable.\n',
+      );
     }
 
     return null;

package/src/core/lib/scope/scope-manager.js

@@ -385,7 +385,7 @@ class ScopeManager {
   resolvePath(template, scopeId) {
     return template
       .replaceAll('{scope}', scopeId)
-      .replaceAll('{output_folder}', this.config?.settings?.default_output_base || '_bmad-output');
+      .replaceAll('{output_folder}', this._config?.settings?.default_output_base || '_bmad-output');
   }
 
   /**

package/src/core/lib/scope/scope-validator.js

@@ -5,11 +5,14 @@ const yaml = require('yaml');
  * @class ScopeValidator
  */
 class ScopeValidator {
-  constructor() {
-    // Scope ID validation pattern: lowercase alphanumeric + hyphens, 2-50 chars
+  // Scope ID validation pattern: lowercase alphanumeric + hyphens, 2-50 chars
+  // IMPORTANT: Must be defined as class field BEFORE constructor to be available in validateScopeId
+  scopeIdPattern = /^[a-z][a-z0-9-]*[a-z0-9]$/;
 
+  constructor() {
     // Reserved scope IDs that cannot be used
-    this.reservedIds = ['_shared', '_events', '_config', 'global', 'default'];
+    // NOTE: 'default' removed from reserved list - it's valid for migration scenarios
+    this.reservedIds = ['_shared', '_events', '_config', '_backup', 'global'];
 
     // Valid isolation modes
     this.validIsolationModes = ['strict', 'warn', 'permissive'];
@@ -288,7 +291,6 @@ class ScopeValidator {
       scopes: {},
     };
   }
-  scopeIdPattern = /^[a-z][a-z0-9-]*[a-z0-9]$/;
 }
 
 module.exports = { ScopeValidator };