forge-workflow 0.0.8 → 0.0.9

package/lib/workflow/state-manager.js

@@ -0,0 +1,193 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { secureExecFileSync } = require('../shell-utils.js');
+const { readWorkflowState, serializeWorkflowState, WORKFLOW_STATE_SCHEMA_VERSION, getAllowedTransitionsForWorkflowState } = require('./state.js');
+const { getWorkflowPath, WORKFLOW_CLASSIFICATIONS, normalizeStageId } = require('./stages.js');
+
+const WORKFLOW_STATE_FILENAME = '.forge-state.json';
+
+function extractWorkflowStateFromComments(comments = '') {
+  const matches = String(comments).match(/^WorkflowState:\s*(\{.*\})$/gm);
+  if (!matches || matches.length === 0) {
+    return null;
+  }
+
+  const latest = matches.at(-1).replace(/^WorkflowState:\s*/, '');
+  return readWorkflowState(latest);
+}
+
+function readWorkflowStateFromBeads(issueId, options = {}) {
+  if (!issueId) {
+    return null;
+  }
+
+  const comments = options.comments || secureExecFileSync('bd', ['comments', 'list', issueId], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  }).trim();
+
+  if (!comments) {
+    return null;
+  }
+
+  return extractWorkflowStateFromComments(comments);
+}
+
+function loadStateFromBeads(options) {
+  if (options.comments) {
+    const state = extractWorkflowStateFromComments(options.comments);
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
+  if (options.issueId) {
+    const state = readWorkflowStateFromBeads(options.issueId, { comments: options.comments });
+    if (state) {
+      return { state, source: 'beads' };
+    }
+  }
+
+  return null;
+}
+
+function loadState(projectRoot, options = {}) {
+  if (!projectRoot) {
+    const beadsResult = loadStateFromBeads(options);
+    return beadsResult || { state: null, source: null };
+  }
+
+  const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
+  if (fs.existsSync(statePath)) {
+    try {
+      const raw = fs.readFileSync(statePath, 'utf8');
+      return { state: readWorkflowState(raw), source: 'file' };
+    } catch (_parseError) {
+      // File is malformed — fall through to Beads fallback
+    }
+  }
+
+  const beadsResult = loadStateFromBeads(options);
+  if (beadsResult) {
+    return beadsResult;
+  }
+
+  return { state: null, source: null };
+}
+
+function saveState(projectRoot, state) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new Error('saveState requires a valid projectRoot path');
+  }
+
+  const normalized = serializeWorkflowState(state);
+  const json = JSON.stringify(normalized, null, 2);
+  const tmpPath = path.join(projectRoot, `${WORKFLOW_STATE_FILENAME}.tmp`);
+  const statePath = path.join(projectRoot, WORKFLOW_STATE_FILENAME);
+
+  fs.writeFileSync(tmpPath, json, 'utf8');
+  fs.renameSync(tmpPath, statePath);
+
+  return normalized;
+}
+
+function initializeState(projectRoot, classification, firstStage) {
+  if (!WORKFLOW_CLASSIFICATIONS.includes(classification)) {
+    throw new Error(`Invalid classification: ${classification}. Expected one of: ${WORKFLOW_CLASSIFICATIONS.join(', ')}`);
+  }
+
+  const workflowPath = getWorkflowPath(classification);
+  const currentStage = firstStage || workflowPath[0];
+
+  const state = {
+    schemaVersion: WORKFLOW_STATE_SCHEMA_VERSION,
+    currentStage,
+    completedStages: [],
+    skippedStages: [],
+    workflowDecisions: {
+      classification,
+      reason: 'initialized',
+      userOverride: false,
+      overrides: [],
+    },
+    parallelTracks: [],
+  };
+
+  return saveState(projectRoot, state);
+}
+
+function transitionStage(projectRoot, toStage, options = {}) {
+  const targetStage = normalizeStageId(toStage);
+  if (!targetStage) {
+    throw new Error(`Invalid target stage: ${toStage}`);
+  }
+
+  const { state: currentState } = loadState(projectRoot, options);
+  if (!currentState) {
+    throw new Error('No workflow state found. Initialize state first with initializeState().');
+  }
+
+  const previousState = JSON.parse(JSON.stringify(currentState));
+  const allowed = getAllowedTransitionsForWorkflowState(currentState);
+
+  if (!allowed.includes(targetStage)) {
+    if (!options.override) {
+      throw new Error(
+        `Transition from ${currentState.currentStage} to ${targetStage} is not allowed. ` +
+        `Allowed transitions: ${allowed.join(', ') || 'none'}. Provide an override to force.`
+      );
+    }
+  }
+
+  const completedStages = [...currentState.completedStages];
+  if (!completedStages.includes(currentState.currentStage)) {
+    completedStages.push(currentState.currentStage);
+  }
+
+  const overrides = [...(currentState.workflowDecisions.overrides || [])];
+  if (options.override) {
+    overrides.push({
+      type: options.override.type || 'manual',
+      fromStage: currentState.currentStage,
+      toStage: targetStage,
+      reason: options.override.reason || '',
+      actor: options.override.actor || 'unknown',
+      userOverride: true,
+      recordedAt: new Date().toISOString(),
+    });
+  }
+
+  const newStateInput = {
+    schemaVersion: currentState.schemaVersion || WORKFLOW_STATE_SCHEMA_VERSION,
+    currentStage: targetStage,
+    completedStages,
+    skippedStages: currentState.skippedStages || [],
+    workflowDecisions: {
+      ...currentState.workflowDecisions,
+      overrides,
+      userOverride: overrides.length > 0,
+    },
+    parallelTracks: currentState.parallelTracks || [],
+  };
+
+  const newState = saveState(projectRoot, newStateInput);
+
+  return {
+    previousState,
+    newState,
+    transitioned: true,
+  };
+}
+
+module.exports = {
+  WORKFLOW_STATE_FILENAME,
+  extractWorkflowStateFromComments,
+  initializeState,
+  loadState,
+  readWorkflowStateFromBeads,
+  saveState,
+  transitionStage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "7-stage TDD workflow for ALL AI coding agents (Claude, Cursor, Cline, OpenCode, Copilot, Kilo Code, Roo Code, Codex)",
   "bin": {
     "forge": "bin/forge.js",

package/scripts/dep-guard.sh

@@ -426,7 +426,7 @@ cmd_check_ripple_keyword_v1() {
 
     # Extract issue ID (forge-xxx pattern)
     local cand_id=""
-    cand_id="$(printf '%s' "$line" | grep -oE 'forge-[a-z0-9]+' | head -1)" || continue
+    cand_id="$(printf '%s' "$line" | grep -oE 'forge-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*' | head -1)" || continue
     [[ -z "$cand_id" ]] && continue
 
     # Skip the source issue itself
@@ -561,6 +561,16 @@ cmd_check_ripple() {
 
   local tmp_dir
   tmp_dir="$(mktemp -d)"
+  # On Windows/Git Bash, normalize to a mixed-mode path so both bash file I/O
+  # and Node.js resolve to the same physical location (cygpath -m → C:/...).
+  # Preserve the original POSIX path if conversion fails or returns empty.
+  if command -v cygpath &>/dev/null; then
+    local mixed_tmp_dir
+    mixed_tmp_dir="$(cygpath -m "$tmp_dir" 2>/dev/null)" || true
+    if [[ -n "$mixed_tmp_dir" && -d "$mixed_tmp_dir" ]]; then
+      tmp_dir="$mixed_tmp_dir"
+    fi
+  fi
   trap 'rm -rf "$tmp_dir"' RETURN
 
   printf '%s' "$src_json" > "${tmp_dir}/current.json"

package/scripts/forge-team/lib/hooks.sh

@@ -148,7 +148,7 @@ forge_team_sync() {
 
     # Extract issue id
     local issue_id
-    issue_id="$(echo "$line" | grep -oE 'forge-[a-zA-Z0-9]+' | head -1)"
+    issue_id="$(echo "$line" | grep -oE 'forge-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*' | head -1)"
     [[ -z "$issue_id" ]] && continue
 
     # Get details to check for github_issue state

package/scripts/forge-team/lib/verify.sh

@@ -75,7 +75,7 @@ _extract_beads_ids() {
   if [[ -z "$input" ]]; then
     return 0
   fi
-  printf '%s\n' "$input" | grep -oP '(forge-[a-z0-9]+)' || true
+  printf '%s\n' "$input" | grep -oP '(forge-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)' || true
 }
 
 # ── Public API ───────────────────────────────────────────────────────────

package/scripts/forge-team/lib/workload.sh

@@ -77,15 +77,38 @@ _status_icon() {
   esac
 }
 
+_json_escape() {
+  local value="${1:-}"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  value="${value//$'\n'/\\n}"
+  value="${value//$'\r'/\\r}"
+  value="${value//$'\t'/\\t}"
+  printf '%s' "$value"
+}
+
 # _collect_issues — Gather all open/in_progress issues with details
 # Outputs lines: id|title|status|owner|updated|depends_on
 _collect_issues() {
   local bd_cmd="${BD_CMD:-bd}"
   local list_output
-  list_output="$("$bd_cmd" list --status=open,in_progress 2>/dev/null)" || return 1
+  local combined_exit=0
+
+  # beads 0.62 rejects comma-separated status filters, so fall back to
+  # separate queries when the combined form fails.
+  list_output="$("$bd_cmd" list --status=open,in_progress 2>/dev/null)"
+  combined_exit=$?
+  if [[ "$combined_exit" -ne 0 ]]; then
+    list_output="$(
+      {
+        "$bd_cmd" list --status=open 2>/dev/null || true
+        "$bd_cmd" list --status=in_progress 2>/dev/null || true
+      } | awk 'NF && !seen[$0]++'
+    )"
+  fi
 
   # Filter empty lines
-  if [[ -z "$list_output" ]] || [[ -z "$(echo "$list_output" | tr -d '[:space:]')" ]]; then
+  if [[ -z "$list_output" ]] || [[ -z "$(printf '%s' "$list_output" | tr -d '[:space:]')" ]]; then
     return 0
   fi
 
@@ -95,7 +118,7 @@ _collect_issues() {
 
     # Extract issue id: first field like "forge-xxx" after optional icon
     local issue_id
-    issue_id="$(echo "$line" | grep -oE 'forge-[a-zA-Z0-9]+' | head -1)"
+    issue_id="$(echo "$line" | grep -oE 'forge-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*' | head -1)"
     [[ -z "$issue_id" ]] && continue
 
     # Get details via bd show
@@ -141,9 +164,10 @@ cmd_workload() {
 
   # Parse arguments
   while [[ $# -gt 0 ]]; do
-    case "$1" in
+    local arg="${1%$'\r'}"
+    case "$arg" in
       --developer=*)
-        filter_developer="${1#--developer=}"
+        filter_developer="${arg#--developer=}"
         shift
         ;;
       --me)
@@ -160,11 +184,11 @@ cmd_workload() {
         shift
         ;;
       --format=*)
-        _workload_error "Unsupported format: ${1#--format=}"
+        _workload_error "Unsupported format: ${arg#--format=}"
         return 1
         ;;
       *)
-        _workload_error "Unknown argument: $1"
+        _workload_error "Unknown argument: $arg"
         return 1
         ;;
     esac
@@ -232,16 +256,13 @@ cmd_workload() {
       [[ -n "$stale_flag" ]] && stale_bool="true"
       local blocked_ids=""
       [[ -n "$depends_on" ]] && blocked_ids="$depends_on"
-
-      # Use jq to build safe JSON
-      jq -n -c \
-        --arg id "$issue_id" \
-        --arg title "$title" \
-        --arg status "$status" \
-        --arg updated "$updated" \
-        --argjson stale "$stale_bool" \
-        --arg blocked_by "$blocked_ids" \
-        '{id: $id, title: $title, status: $status, updated: $updated, stale: $stale, blocked_by: $blocked_by}' \
+      printf '{"id":"%s","title":"%s","status":"%s","updated":"%s","stale":%s,"blocked_by":"%s"}\n' \
+        "$(_json_escape "$issue_id")" \
+        "$(_json_escape "$title")" \
+        "$(_json_escape "$status")" \
+        "$(_json_escape "$updated")" \
+        "$stale_bool" \
+        "$(_json_escape "$blocked_ids")" \
         >> "$work_dir/json/${owner}"
     fi
   done <<< "$issues_data"
@@ -260,22 +281,30 @@ cmd_workload() {
   # Output
   if [[ "$format" == "json" ]]; then
     # Build JSON object: { "devone": [...], "devtwo": [...] }
-    local json_result="{"
-    local first=true
+    local first_dev="true"
+    printf '{'
     for dev_file in "$work_dir/json"/*; do
       local dev_name
       dev_name="$(basename "$dev_file")"
-      local issues_array
-      issues_array="$(jq -s '.' "$dev_file")"
-      if [[ "$first" == "true" ]]; then
-        first=false
+      local first_issue="true"
+      if [[ "$first_dev" == "true" ]]; then
+        first_dev="false"
       else
-        json_result+=","
+        printf ','
       fi
-      json_result+="$(jq -n -c --arg dev "$dev_name" --argjson issues "$issues_array" '{($dev): $issues}' | sed 's/^{//' | sed 's/}$//')"
+      printf '"%s":[' "$(_json_escape "$dev_name")"
+      while IFS= read -r issue_json; do
+        [[ -z "$issue_json" ]] && continue
+        if [[ "$first_issue" == "true" ]]; then
+          first_issue="false"
+        else
+          printf ','
+        fi
+        printf '%s' "$issue_json"
+      done < "$dev_file"
+      printf ']'
     done
-    json_result+="}"
-    echo "$json_result"
+    printf '}\n'
   else
     local first_dev=true
     for dev_file in "$work_dir/devs"/*; do

package/scripts/forge-team/tests/workload.test.sh

@@ -32,9 +32,15 @@ cat > "$mock_dir/bd" << 'MOCK'
 #!/usr/bin/env bash
 case "$1 $2" in
   "list --status=open,in_progress")
-    echo "◐ forge-aaa · Feature A"
+    exit 1
+    ;;
+  "list --status=open")
     echo "○ forge-bbb · Feature B"
+    ;;
+  "list --status=in_progress")
+    echo "◐ forge-aaa · Feature A"
     echo "◐ forge-ccc · Feature C"
+    echo "◐ forge-m1n8.6 · Sub-feature X (dotted ID)"
     ;;
   "show forge-aaa")
     echo "◐ forge-aaa · Feature A [● P2 · IN_PROGRESS]"
@@ -54,6 +60,19 @@ case "$1 $2" in
     echo "DEPENDS ON"
     echo "  → forge-aaa: Feature A"
     ;;
+  "show forge-m1n8.6")
+    # Dotted sub-ID — bd show must receive the full ID including .6
+    echo "◐ forge-m1n8.6 · Sub-feature X [● P2 · IN_PROGRESS]"
+    echo "Owner: devthree"
+    echo "Updated: 2026-03-27T08:00:00Z"
+    ;;
+  "show forge-m1n8")
+    # Parent epic — if a buggy parser truncates forge-m1n8.6 to forge-m1n8,
+    # the workload would get this WRONG owner and trigger the guard below.
+    echo "◐ forge-m1n8 · PARENT EPIC (WRONG — dotted ID was truncated)"
+    echo "Owner: WRONG_OWNER_DO_NOT_USE"
+    echo "Updated: 2026-03-20T10:00:00Z"
+    ;;
 esac
 MOCK
 chmod +x "$mock_dir/bd"
@@ -65,6 +84,12 @@ case "$1 $2" in
   "list --status=open,in_progress")
     echo ""
     ;;
+  "list --status=open")
+    echo "○ forge-should-not-appear · Open fallback sentinel"
+    ;;
+  "list --status=in_progress")
+    echo "◐ forge-should-not-appear-2 · In-progress fallback sentinel"
+    ;;
 esac
 MOCK
 chmod +x "$mock_dir/bd-empty"
@@ -125,6 +150,11 @@ assert_contains "shows devtwo header" "Developer: devtwo" "$output"
 assert_contains "shows forge-aaa" "forge-aaa" "$output"
 assert_contains "shows forge-bbb" "forge-bbb" "$output"
 assert_contains "shows forge-ccc" "forge-ccc" "$output"
+# Dotted ID regression (forge-hpev): the full forge-m1n8.6 must be extracted,
+# not truncated to forge-m1n8. devthree owns the sub-issue, not WRONG_OWNER.
+assert_contains "shows devthree (dotted ID owner)" "Developer: devthree" "$output"
+assert_contains "shows dotted ID forge-m1n8.6 in full" "forge-m1n8.6" "$output"
+assert_not_contains "does NOT attribute to WRONG_OWNER (parent epic)" "WRONG_OWNER" "$output"
 
 # ── Test 2: --developer=devone filters correctly ─────────────────────────
 echo ""
@@ -158,6 +188,7 @@ rc=0
 output="$(cmd_workload 2>/dev/null)" || rc=$?
 assert_exit "exits 0" 0 "$rc"
 assert_contains "shows no active work message" "No active work" "$output"
+assert_not_contains "does not fall back when combined query succeeds with no issues" "forge-should-not-appear" "$output"
 export BD_CMD="$mock_dir/bd"
 
 # ── Test 5: Stale assignment flagged (>48h) ──────────────────────────────
@@ -178,18 +209,18 @@ rc=0
 output="$(cmd_workload --format=json 2>/dev/null)" || rc=$?
 assert_exit "exits 0" 0 "$rc"
 # Validate it's parseable JSON
-if echo "$output" | jq . >/dev/null 2>&1; then
+if echo "$output" | node -e 'JSON.parse(require("fs").readFileSync(0, "utf8"));' >/dev/null 2>&1; then
   PASS=$((PASS + 1)); echo "  PASS: output is valid JSON"
 else
   FAIL=$((FAIL + 1)); echo "  FAIL: output is not valid JSON: $output"
 fi
 # Check JSON has developer keys
-if echo "$output" | jq -e '.devone' >/dev/null 2>&1; then
+if echo "$output" | node -e 'const data = JSON.parse(require("fs").readFileSync(0, "utf8")); process.exit(data.devone ? 0 : 1);' >/dev/null 2>&1; then
   PASS=$((PASS + 1)); echo "  PASS: JSON contains devone key"
 else
   FAIL=$((FAIL + 1)); echo "  FAIL: JSON missing devone key"
 fi
-if echo "$output" | jq -e '.devtwo' >/dev/null 2>&1; then
+if echo "$output" | node -e 'const data = JSON.parse(require("fs").readFileSync(0, "utf8")); process.exit(data.devtwo ? 0 : 1);' >/dev/null 2>&1; then
   PASS=$((PASS + 1)); echo "  PASS: JSON contains devtwo key"
 else
   FAIL=$((FAIL + 1)); echo "  FAIL: JSON missing devtwo key"

package/scripts/github-beads-sync/run-bd.mjs

@@ -79,10 +79,12 @@ export function buildSearchArgs(query) {
  * @returns {string|null}
  */
 export function parseCreateOutput(stdout) {
-  const match = stdout.match(/Created issue:\s+(forge-[\w-]+)/);
+  // Match forge-xxx with optional dotted sub-IDs (e.g. forge-m1n8.6, forge-dq8j.1).
+  // \w in JS doesn't include '.', so the dotted sub-ID group is explicit.
+  const match = stdout.match(/Created issue:\s+(forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*)/);
   if (match) return match[1];
   // Fallback: loose match for any forge-prefixed ID anywhere in output
-  const fallback = stdout.match(/(forge-[a-z0-9]+)/i);
+  const fallback = stdout.match(/(forge-[a-zA-Z0-9]+(?:\.[a-zA-Z0-9]+)*)/);
   return fallback ? fallback[1] : null;
 }
 

package/scripts/smart-status.sh

@@ -68,7 +68,9 @@ if ! command -v jq &>/dev/null; then
 fi
 
 # Warn if jq < 1.6 (fromdateiso8601 and sub/2 require 1.6+)
-_jq_version="$(jq --version 2>/dev/null | sed 's/jq-//')" || true
+# Strip CR here as well because Windows jq.exe (or a CRLF-emitting wrapper in
+# tests) can affect the version probe before the jq() shim is defined below.
+_jq_version="$(command jq --version 2>/dev/null | tr -d '\r' | sed 's/jq-//')" || true
 if [ -n "$_jq_version" ]; then
   _jq_major="${_jq_version%%.*}"
   _jq_minor="${_jq_version#*.}"; _jq_minor="${_jq_minor%%.*}"
@@ -77,6 +79,13 @@ if [ -n "$_jq_version" ]; then
   fi
 fi
 
+# On Windows/WSL we may be invoking jq.exe, which emits CRLF and breaks
+# numeric comparisons like `[ "$count" -gt 0 ]`. Strip trailing CRs from
+# all jq output after the dependency/version checks above.
+jq() {
+  command jq "$@" | tr -d '\r'
+}
+
 # ── Configuration ───────────────────────────────────────────────────────
 
 BD="${BD_CMD:-bd}"

package/scripts/sync-utils.sh

@@ -271,16 +271,55 @@ _run_sync() {
   fi
 }
 
+_has_dolt_remote() {
+  local remote_name="${1:-origin}"
+  local remote_list=""
+  local raw_output=""
+  local bd_cmd="${BD_CMD:-bd}"
+  local remote_status=0
+
+  if ! command -v "$bd_cmd" >/dev/null 2>&1; then
+    return 2
+  fi
+
+  raw_output="$("$bd_cmd" dolt remote list 2>/dev/null)"
+  remote_status=$?
+  if [[ "$remote_status" -ne 0 ]]; then
+    return 2
+  fi
+  remote_list="$(printf '%s' "$raw_output" | tr -d '\r')"
+
+  if [[ -z "$remote_list" ]]; then
+    return 1
+  fi
+
+  printf '%s\n' "$remote_list" | awk 'NF { print $1 }' | grep -Fqx -- "$remote_name"
+}
+
 # Environment overrides (for testing):
 #   BD_SYNC_CMD — single command to run instead of default pull+push (e.g. "echo mock-sync")
 #   FILE_INDEX_ROOT — root directory for file-index.sh (default: repo_dir)
 auto_sync() {
   local repo_dir="${1:-.}"
   local last_sync_file="$repo_dir/.beads/.last-sync"
+  local sync_remote
+  sync_remote="$(get_sync_remote "$repo_dir")"
 
   # Ensure .beads directory exists
   mkdir -p "$repo_dir/.beads"
 
+  if _has_dolt_remote "$sync_remote"; then
+    :
+  else
+    local remote_status=$?
+    if [[ "$remote_status" -eq 2 ]]; then
+      echo "Warning: sync skipped, unable to inspect Beads Dolt remotes (is 'bd' installed and configured?)." >&2
+    else
+      echo "Warning: sync skipped, Beads Dolt remote '$sync_remote' is not configured (run 'bd dolt remote add $sync_remote <url>')." >&2
+    fi
+    return 0
+  fi
+
   # Run sync — helper function avoids eval while supporting compound default
   if _run_sync >/dev/null 2>&1; then
     # Success: record timestamp