dashboard: auto-switch worktrees on navigation and document new FIRE run id format

hancengiz · hancengiz · commit d3e3d621786b · 2026-02-22T16:59:53.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 You can also view this changelog at [specs.md/changelog](https://specs.md/changelog).
 
+## [0.1.27] - 2026-02-22
+
+### Changed
+
+- FIRE: Standardized run IDs to `run-<worktree>-NNN` (for example, `run-fabriqa-2026-001`)
+- FIRE: Run numbering now increments per worktree slug to avoid ID collisions when multiple agents run in parallel across different git worktrees
+- FIRE: Updated FIRE documentation and skill examples to the new run ID convention while keeping legacy `run-001` histories readable
+
 ## [0.1.26] - 2026-02-21
 
 ### Added
@@ -213,6 +221,7 @@ The VS Code extension now shows real-time phase progress for each work item in F
 
 ---
 
+[0.1.27]: https://github.com/fabriqaai/specs.md/compare/v0.1.26...v0.1.27
 [0.1.26]: https://github.com/fabriqaai/specs.md/compare/v0.1.25...v0.1.26
 [0.1.23]: https://github.com/fabriqaai/specs.md/compare/v0.1.22...v0.1.23
 [0.1.11]: https://github.com/fabriqaai/specs.md/compare/v0.1.10...v0.1.11
diff --git a/docs.specs.md/changelog.mdx b/docs.specs.md/changelog.mdx
@@ -10,6 +10,14 @@ All notable changes to specs.md.
   **Subscribe to updates:** [RSS Feed](/changelog/rss.xml) | [GitHub Releases](https://github.com/fabriqaai/specs.md/releases)
 </Info>
 
+<Update label="February 22, 2026" description="v0.1.27" tags={["FIRE", "CLI", "Worktrees"]}>
+### Changed
+
+- Standardized FIRE run IDs to `run-<worktree>-NNN` (for example, `run-fabriqa-2026-001`)
+- Added per-worktree run numbering semantics to prevent collisions during parallel agent execution on different git worktrees
+- Updated FIRE documentation and skill examples to the new run ID convention while preserving compatibility with historical `run-001` records
+</Update>
+
 <Update label="February 21, 2026" description="v0.1.26" tags={["FIRE", "CLI", "Codex"]}>
 ### Added
 
diff --git a/docs.specs.md/fire-flow/agents.mdx b/docs.specs.md/fire-flow/agents.mdx
@@ -303,7 +303,7 @@ Executing...
 ✓ Created tests/routes/auth.test.ts
 ✓ Modified src/routes/index.ts
 
-Walkthrough generated: walkthroughs/run-002-login-endpoint.md
+Walkthrough generated: walkthroughs/run-fabriqa-2026-002-login-endpoint.md
 
 ---
 Work item complete. Next: password-reset
diff --git a/docs.specs.md/fire-flow/quick-start.mdx b/docs.specs.md/fire-flow/quick-start.mdx
@@ -142,7 +142,7 @@ Executing...
     ✓ Added User model: src/models/user.ts
     ✓ Updated schema exports
 
-    Walkthrough generated: walkthroughs/run-001-user-schema.md
+    Walkthrough generated: walkthroughs/run-fabriqa-2026-001-user-schema.md
     ```
   </Accordion>
   <Accordion title="Confirm Mode (1 checkpoint)">
diff --git a/docs.specs.md/fire-flow/work-items.mdx b/docs.specs.md/fire-flow/work-items.mdx
@@ -225,7 +225,7 @@ run:
     modified:
       - src/models/index.ts
     deleted: []
-  walkthrough: walkthroughs/run-001-user-schema.md
+  walkthrough: walkthroughs/run-fabriqa-2026-001-user-schema.md
 ```
 
 ## Walkthroughs
@@ -235,7 +235,7 @@ A **Walkthrough** is generated after each successful run. It documents what chan
 ### Structure
 
 ```markdown
-# Run 001: user-schema
+# Run run-fabriqa-2026-001: user-schema
 
 ## Summary
 Created user database schema with email/password authentication fields.
diff --git a/src/flows/fire/agents/builder/agent.md b/src/flows/fire/agents/builder/agent.md
@@ -124,7 +124,7 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
 
   ```yaml
   run:
-    id: run-001
+    id: run-fabriqa-2026-001
     scope: batch  # single | batch | wide
     work_items:
       - id: login-endpoint
@@ -159,7 +159,7 @@ You are the **Builder Agent** for FIRE (Fast Intent-Run Engineering).
   | Create run.md | (handled by init-run.cjs) | ❌ NO direct write |
   | Update state.yaml | (handled by scripts) | ❌ NO direct edit |
 
-  <check if="about to mkdir .specs-fire/runs/run-XXX">
+  <check if="about to mkdir .specs-fire/runs/run-<worktree>-XXX">
     <action>STOP — use init-run.cjs instead</action>
   </check>
   <check if="about to edit state.yaml directly">
diff --git a/src/flows/fire/agents/builder/skills/code-review/SKILL.md b/src/flows/fire/agents/builder/skills/code-review/SKILL.md
@@ -42,7 +42,7 @@ Review code written during a run, auto-fix no-brainer issues, and suggest improv
     - path: src/routes/index.ts
       changes: Added login route
 
-  run_id: run-001
+  run_id: run-fabriqa-2026-001
   intent_id: user-auth
   ```
 
diff --git a/src/flows/fire/agents/builder/skills/run-execute/SKILL.md b/src/flows/fire/agents/builder/skills/run-execute/SKILL.md
@@ -548,8 +548,8 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
-        "runPath": "/project/.specs-fire/runs/run-001",
+        "runId": "run-fabriqa-2026-001",
+        "runPath": "/project/.specs-fire/runs/run-fabriqa-2026-001",
         "scope": "batch",
         "workItems": [...],
         "currentItem": "wi-1"
@@ -561,10 +561,10 @@ Supports both single-item and multi-item (batch/wide) runs.
   <script name="complete-run.cjs">
     ```bash
     # Complete current item (batch runs - moves to next item)
-    node scripts/complete-run.cjs /project run-001 --complete-item
+    node scripts/complete-run.cjs /project run-fabriqa-2026-001 --complete-item
 
     # Complete entire run (single runs or final item in batch)
-    node scripts/complete-run.cjs /project run-001 --complete-run \
+    node scripts/complete-run.cjs /project run-fabriqa-2026-001 --complete-run \
       --files-created='[{"path":"src/new.ts","purpose":"New feature"}]' \
       --files-modified='[{"path":"src/old.ts","changes":"Added import"}]' \
       --tests=5 --coverage=85
@@ -574,7 +574,7 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
+        "runId": "run-fabriqa-2026-001",
         "completedItem": "wi-1",
         "nextItem": "wi-2",
         "remainingItems": 1,
@@ -587,7 +587,7 @@ Supports both single-item and multi-item (batch/wide) runs.
       ```json
       {
         "success": true,
-        "runId": "run-001",
+        "runId": "run-fabriqa-2026-001",
         "scope": "batch",
         "workItemsCompleted": 2,
         "completedAt": "2026-01-20T..."
@@ -619,7 +619,7 @@ Supports both single-item and multi-item (batch/wide) runs.
   After init-run.cjs creates a run:
 
   ```
-  .specs-fire/runs/run-001/
+  .specs-fire/runs/run-fabriqa-2026-001/
   ├── run.md           # Created by init-run.cjs, updated by complete-run.cjs
   ├── plan.md          # Created BEFORE implementation (ALL modes - required)
   ├── test-report.md   # Created AFTER tests pass (required)
diff --git a/src/flows/fire/agents/builder/skills/run-status/SKILL.md b/src/flows/fire/agents/builder/skills/run-status/SKILL.md
@@ -58,7 +58,7 @@ Display current run status and progress.
 <example_output>
 
   ```
-  ## Run Status: run-003
+  ## Run Status: run-fabriqa-2026-003
 
   **Work Item**: Add session management
   **Intent**: User Authentication
diff --git a/src/flows/fire/agents/orchestrator/agent.md b/src/flows/fire/agents/orchestrator/agent.md
@@ -103,7 +103,7 @@ You are the **Orchestrator Agent** for FIRE (Fast Intent-Run Engineering).
   runs:
     active: []  # List of active runs (supports multiple parallel runs)
     completed:
-      - id: run-001
+      - id: run-fabriqa-2026-001
         work_items:
           - id: login-endpoint
             intent: user-auth
diff --git a/src/flows/fire/agents/orchestrator/skills/status/SKILL.md b/src/flows/fire/agents/orchestrator/skills/status/SKILL.md
@@ -639,7 +639,7 @@ Detect inconsistencies and offer interactive resolution.
 
   ## Active Runs
 
-  - **Run**: run-002 | **Scope**: single
+  - **Run**: run-fabriqa-2026-002 | **Scope**: single
   - **Current Item**: session-management
   - **Started**: 2026-01-19T10:30:00Z
 
@@ -657,7 +657,7 @@ Detect inconsistencies and offer interactive resolution.
 
   | # | Type | Location | Issue | Suggested Fix |
   |---|------|----------|-------|---------------|
-  | 1 | 🟡 | run-002 | Run started 3 days ago, may be stale | Resume or abandon |
+  | 1 | 🟡 | run-fabriqa-2026-002 | Run started 3 days ago, may be stale | Resume or abandon |
   | 2 | 🔵 | login-endpoint | Frontmatter says 'pending' but state says 'completed' | Sync frontmatter |
   | 3 | 🟡 | analytics-dashboard.md | Work item on disk but not tracked | Add to state.yaml |
 
diff --git a/src/flows/fire/memory-bank.yaml b/src/flows/fire/memory-bank.yaml
@@ -66,7 +66,7 @@ state:
       - active: "List of currently active runs (supports multiple parallel runs)"
       - completed: "List of completed runs with id, work_item, intent, completed timestamp"
     # Each run (active or completed) has:
-    #   - id: "Run ID (e.g., run-001)"
+    #   - id: "Run ID (e.g., run-fabriqa-2026-001)"
     #   - scope: "single | batch | wide"
     #   - work_items: "List of work items in this run"
     #   - current_item: "Work item currently being executed (active runs only)"
@@ -93,9 +93,9 @@ naming:
     note: "Kebab-case, action-oriented name"
 
   runs:
-    format: "run-{NNN}/"
-    example: "run-001/"
-    note: "Sequential 3-digit number, folder per run"
+    format: "run-{worktree}-{NNN}/"
+    example: "run-fabriqa-2026-001/"
+    note: "Sequential 3-digit number per worktree, folder per run"
     contents:
       - "run.md"           # Run log (created by init-run.cjs)
       - "plan.md"          # Implementation plan (ALL modes, created BEFORE implementation)
diff --git a/src/lib/dashboard/tui/app.js b/src/lib/dashboard/tui/app.js
@@ -2308,6 +2308,20 @@ function rowToFileEntry(row) {
   };
 }
 
+function rowToWorktreeId(row) {
+  if (!row || typeof row.key !== 'string') {
+    return null;
+  }
+
+  const prefix = 'worktree:item:';
+  if (!row.key.startsWith(prefix)) {
+    return null;
+  }
+
+  const worktreeId = row.key.slice(prefix.length).trim();
+  return worktreeId === '' ? null : worktreeId;
+}
+
 function moveRowSelection(rows, currentIndex, direction) {
   if (!Array.isArray(rows) || rows.length === 0) {
     return 0;
@@ -3093,12 +3107,15 @@ function createDashboardApp(deps) {
     const selectedFocusedRow = getSelectedRow(focusedRows, focusedIndex);
     const selectedFocusedFile = rowToFileEntry(selectedFocusedRow);
 
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (overrideSelectedWorktreeId = null) => {
       const now = new Date().toISOString();
+      const requestedWorktreeId = typeof overrideSelectedWorktreeId === 'string' && overrideSelectedWorktreeId.trim() !== ''
+        ? overrideSelectedWorktreeId.trim()
+        : selectedWorktreeId;
 
       try {
         const result = await parseSnapshotForActiveFlow(activeFlow, {
-          selectedWorktreeId
+          selectedWorktreeId: requestedWorktreeId
         });
 
         if (result?.ok) {
@@ -3149,6 +3166,40 @@ function createDashboardApp(deps) {
       }
     }, [activeFlow, parseSnapshotForActiveFlow, selectedWorktreeId, watchEnabled]);
 
+    const switchToWorktree = useCallback((nextWorktreeId, options = {}) => {
+      const normalizedNextId = typeof nextWorktreeId === 'string' ? nextWorktreeId.trim() : '';
+      if (normalizedNextId === '') {
+        setStatusLine('No worktree selected.');
+        return false;
+      }
+
+      const nextItem = worktreeItems.find((item) => item.id === normalizedNextId);
+      if (!nextItem) {
+        setStatusLine('Selected worktree is no longer available.');
+        return false;
+      }
+
+      if (!nextItem.flowAvailable) {
+        setStatusLine(`Flow is unavailable in worktree: ${getWorktreeDisplayName(nextItem)}`);
+        return false;
+      }
+
+      const changed = normalizedNextId !== selectedWorktreeId;
+      setSelectedWorktreeId(normalizedNextId);
+      setPreviewTarget(null);
+      setPreviewOpen(false);
+      setOverlayPreviewOpen(false);
+      setPreviewScroll(0);
+      setPaneFocus('main');
+
+      if (changed || options.forceRefresh) {
+        setStatusLine(`Switched to worktree: ${getWorktreeDisplayName(nextItem)}`);
+        void refresh(normalizedNextId);
+      }
+
+      return true;
+    }, [refresh, selectedWorktreeId, worktreeItems]);
+
     useInput((input, key) => {
       if ((key.ctrl && input === 'c') || input === 'q') {
         exit();
@@ -3192,20 +3243,8 @@ function createDashboardApp(deps) {
 
         if (key.return || key.enter) {
           const selectedOverlayItem = worktreeItems[clampIndex(worktreeOverlayIndex, worktreeItems.length || 1)];
-          if (!selectedOverlayItem) {
-            setStatusLine('No worktree selected.');
-            setWorktreeOverlayOpen(false);
-            return;
-          }
-          setSelectedWorktreeId(selectedOverlayItem.id);
+          switchToWorktree(selectedOverlayItem?.id || '', { forceRefresh: true });
           setWorktreeOverlayOpen(false);
-          setPreviewTarget(null);
-          setPreviewOpen(false);
-          setOverlayPreviewOpen(false);
-          setPreviewScroll(0);
-          setPaneFocus('main');
-          setStatusLine(`Switched to worktree: ${getWorktreeDisplayName(selectedOverlayItem)}`);
-          void refresh();
           return;
         }
 
@@ -3460,6 +3499,15 @@ function createDashboardApp(deps) {
           ...previous,
           [targetSection]: nextIndex
         }));
+
+        if (targetSection === 'worktrees' && worktreeSectionEnabled) {
+          const nextRow = getSelectedRow(targetRows, nextIndex);
+          const nextWorktreeId = rowToWorktreeId(nextRow);
+          if (nextWorktreeId && nextWorktreeId !== selectedWorktreeId) {
+            switchToWorktree(nextWorktreeId);
+          }
+        }
+
         return;
       }
 
