specsmd 0.1.46 → 0.1.50

package/bin/cli.js

@@ -24,6 +24,7 @@ program
     .description('Live terminal dashboard for flow state (FIRE first)')
     .option('--flow <flow>', 'Flow to inspect (fire|aidlc|simple), default auto-detect')
     .option('--path <dir>', 'Workspace path', process.cwd())
+    .option('--worktree <nameOrPath>', 'Initial git worktree (branch name, worktree name, id, or absolute path)')
     .option('--refresh-ms <n>', 'Fallback refresh interval in milliseconds (default: 1000)', '1000')
     .option('--no-watch', 'Render once and exit')
     .action((options) => dashboard.run(options));

package/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">

package/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
   ```
 

package/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)

package/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

package/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

package/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 |
 

package/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)

package/lib/dashboard/git/worktrees.js

@@ -0,0 +1,248 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function normalizePath(value) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return null;
+  }
+  try {
+    return path.resolve(value.trim());
+  } catch {
+    return null;
+  }
+}
+
+function parseBranchName(refLine) {
+  if (typeof refLine !== 'string' || refLine.trim() === '') {
+    return '';
+  }
+  const prefix = 'refs/heads/';
+  if (refLine.startsWith(prefix)) {
+    return refLine.slice(prefix.length);
+  }
+  return refLine.trim();
+}
+
+function buildWorktreeId(worktreePath) {
+  return String(worktreePath || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9/_-]+/g, '-');
+}
+
+function parseGitWorktreePorcelain(rawOutput, fallbackWorkspacePath = process.cwd()) {
+  const text = String(rawOutput || '');
+  const blocks = text
+    .split(/\n\s*\n/g)
+    .map((block) => block.trim())
+    .filter(Boolean);
+
+  const worktrees = [];
+  for (const block of blocks) {
+    const lines = block.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0) {
+      continue;
+    }
+
+    const pathLine = lines.find((line) => line.startsWith('worktree '));
+    if (!pathLine) {
+      continue;
+    }
+
+    const worktreePath = normalizePath(pathLine.slice('worktree '.length));
+    if (!worktreePath) {
+      continue;
+    }
+
+    const branchRef = (lines.find((line) => line.startsWith('branch ')) || '').slice('branch '.length);
+    const head = (lines.find((line) => line.startsWith('HEAD ')) || '').slice('HEAD '.length);
+    const detached = lines.includes('detached');
+    const prunable = lines.some((line) => line.startsWith('prunable'));
+    const locked = lines.some((line) => line.startsWith('locked'));
+    const branch = parseBranchName(branchRef);
+    const name = path.basename(worktreePath);
+    const displayBranch = detached ? `[detached:${head.slice(0, 7) || 'unknown'}]` : (branch || '[unknown]');
+
+    worktrees.push({
+      id: buildWorktreeId(worktreePath),
+      path: worktreePath,
+      name,
+      branch,
+      displayBranch,
+      head: head || '',
+      detached,
+      prunable,
+      locked,
+      isMainBranch: branch === 'main' || branch === 'master',
+      isCurrentPath: false
+    });
+  }
+
+  if (worktrees.length === 0) {
+    const fallbackPath = normalizePath(fallbackWorkspacePath) || normalizePath(process.cwd()) || process.cwd();
+    return [{
+      id: buildWorktreeId(fallbackPath),
+      path: fallbackPath,
+      name: path.basename(fallbackPath),
+      branch: '',
+      displayBranch: '[non-git]',
+      head: '',
+      detached: false,
+      prunable: false,
+      locked: false,
+      isMainBranch: false,
+      isCurrentPath: true
+    }];
+  }
+
+  return worktrees;
+}
+
+function markCurrentWorktree(worktrees, workspacePath) {
+  const currentPath = normalizePath(workspacePath);
+  const safeWorktrees = Array.isArray(worktrees) ? worktrees : [];
+  const marked = safeWorktrees.map((worktree) => ({
+    ...worktree,
+    isCurrentPath: currentPath != null && normalizePath(worktree.path) === currentPath
+  }));
+
+  if (marked.some((worktree) => worktree.isCurrentPath)) {
+    return marked;
+  }
+
+  if (currentPath) {
+    return marked.map((worktree, index) => ({
+      ...worktree,
+      isCurrentPath: index === 0
+    }));
+  }
+
+  return marked;
+}
+
+function sortWorktrees(worktrees) {
+  const safeWorktrees = Array.isArray(worktrees) ? [...worktrees] : [];
+  return safeWorktrees.sort((a, b) => {
+    if (a.isCurrentPath !== b.isCurrentPath) {
+      return a.isCurrentPath ? -1 : 1;
+    }
+    if (a.isMainBranch !== b.isMainBranch) {
+      return a.isMainBranch ? -1 : 1;
+    }
+    return String(a.displayBranch || a.name || '').localeCompare(String(b.displayBranch || b.name || ''));
+  });
+}
+
+function isGitWorkspace(workspacePath) {
+  const cwd = normalizePath(workspacePath) || process.cwd();
+  const result = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+    cwd,
+    encoding: 'utf8'
+  });
+  if (result.error || result.status !== 0) {
+    return false;
+  }
+  return String(result.stdout || '').trim() === 'true';
+}
+
+function discoverGitWorktrees(workspacePath) {
+  const cwd = normalizePath(workspacePath) || process.cwd();
+  if (!isGitWorkspace(cwd)) {
+    return {
+      worktrees: markCurrentWorktree(parseGitWorktreePorcelain('', cwd), cwd),
+      source: 'fallback',
+      isGitRepo: false
+    };
+  }
+
+  const result = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+    cwd,
+    encoding: 'utf8'
+  });
+
+  if (result.error || result.status !== 0) {
+    return {
+      worktrees: markCurrentWorktree(parseGitWorktreePorcelain('', cwd), cwd),
+      source: 'fallback',
+      isGitRepo: true,
+      error: result.error ? result.error.message : String(result.stderr || '').trim()
+    };
+  }
+
+  const parsed = parseGitWorktreePorcelain(result.stdout, cwd);
+  const marked = markCurrentWorktree(parsed, cwd);
+  return {
+    worktrees: sortWorktrees(marked),
+    source: 'git',
+    isGitRepo: true
+  };
+}
+
+function pickWorktree(worktrees, selector, workspacePath) {
+  const safeWorktrees = Array.isArray(worktrees) ? worktrees : [];
+  if (safeWorktrees.length === 0) {
+    return null;
+  }
+
+  const normalizedSelector = String(selector || '').trim();
+  const selectorPath = normalizePath(normalizedSelector);
+  const currentPath = normalizePath(workspacePath);
+
+  if (normalizedSelector !== '') {
+    const byId = safeWorktrees.find((item) => item.id === normalizedSelector);
+    if (byId) {
+      return byId;
+    }
+
+    if (selectorPath) {
+      const byPath = safeWorktrees.find((item) => normalizePath(item.path) === selectorPath);
+      if (byPath) {
+        return byPath;
+      }
+    }
+
+    const byBranch = safeWorktrees.find((item) => item.branch === normalizedSelector || item.displayBranch === normalizedSelector);
+    if (byBranch) {
+      return byBranch;
+    }
+
+    const byName = safeWorktrees.find((item) => item.name === normalizedSelector);
+    if (byName) {
+      return byName;
+    }
+  }
+
+  if (currentPath) {
+    const byCurrentPath = safeWorktrees.find((item) => normalizePath(item.path) === currentPath);
+    if (byCurrentPath) {
+      return byCurrentPath;
+    }
+  }
+
+  const markedCurrent = safeWorktrees.find((item) => item.isCurrentPath);
+  if (markedCurrent) {
+    return markedCurrent;
+  }
+
+  return safeWorktrees[0];
+}
+
+function pathExistsAsDirectory(targetPath) {
+  try {
+    return fs.statSync(targetPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  normalizePath,
+  parseBranchName,
+  parseGitWorktreePorcelain,
+  markCurrentWorktree,
+  sortWorktrees,
+  isGitWorkspace,
+  discoverGitWorktrees,
+  pickWorktree,
+  pathExistsAsDirectory
+};