forge-workflow 0.0.5 → 0.0.7

package/scripts/beads-context.sh

@@ -7,13 +7,18 @@
 #   set-acceptance   <issue-id> "<criteria-text>"
 #   update-progress  <issue-id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>
 #   parse-progress   <issue-id>
-#   stage-transition <issue-id> <completed-stage> <next-stage>
+#   stage-transition <issue-id> <completed-stage> <next-stage> [--summary "..."] [--decisions "..."] [--artifacts "..."] [--next "..."] [--workflow-state "{...}"]
+#   validate         <issue-id>
 #
 # Cross-platform: works on Windows (Git Bash), macOS, and Linux.
 # OWASP A03: All variables properly quoted to prevent shell injection.
 
 set -euo pipefail
 
+# Source shared sanitize library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/sanitize.sh"
+
 # ── Helpers ──────────────────────────────────────────────────────────────
 
 usage() {
@@ -25,7 +30,8 @@ Subcommands:
   set-acceptance   <issue-id> "<criteria-text>"
   update-progress  <issue-id> <task-num> <total> "<title>" <commit-sha> <test-count> <gate-count>
   parse-progress   <issue-id>
-  stage-transition <issue-id> <completed-stage> <next-stage>
+  stage-transition <issue-id> <completed-stage> <next-stage> [--summary "..."] [--decisions "..."] [--artifacts "..."] [--next "..."] [--workflow-state "{...}"]
+  validate         <issue-id>
 EOF
   exit 1
 }
@@ -35,24 +41,6 @@ die() {
   exit 1
 }
 
-# Sanitize a string: strip shell-injection patterns (OWASP A03)
-# Removes: double quotes, $(...), backticks, semicolons, and newlines
-sanitize() {
-  local val="$1"
-  # Remove double quotes
-  val="${val//\"/}"
-  # Remove $(...) command substitution patterns (loop handles nested)
-  # Use newline-separated commands for BSD sed compatibility (macOS)
-  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
-  # Remove backtick command substitution
-  val="${val//\`/}"
-  # Remove semicolons (command chaining)
-  val="${val//;/}"
-  # Replace newlines with spaces
-  val="$(printf '%s' "$val" | tr '\n' ' ')"
-  printf '%s' "$val"
-}
-
 # Run bd update and check for errors in both exit code and output.
 # bd update exits 0 even for non-existent issues, so we check stdout too.
 bd_update() {
@@ -250,7 +238,7 @@ cmd_parse_progress() {
 
 cmd_stage_transition() {
   if [[ $# -lt 3 ]]; then
-    echo "Usage: beads-context.sh stage-transition <issue-id> <completed-stage> <next-stage>" >&2
+    echo "Usage: beads-context.sh stage-transition <issue-id> <completed-stage> <next-stage> [--summary \"...\"] [--decisions \"...\"] [--artifacts \"...\"] [--next \"...\"] [--workflow-state \"{...}\"]" >&2
     exit 1
   fi
 
@@ -259,9 +247,64 @@ cmd_stage_transition() {
   completed="$(sanitize "$2")"
   local next
   next="$(sanitize "$3")"
-
+  shift 3
+
+  # Parse optional flags
+  local flag_summary="" flag_decisions="" flag_artifacts="" flag_next="" flag_workflow_state=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --summary)
+        shift
+        flag_summary="$(sanitize "${1:-}")"
+        ;;
+      --decisions)
+        shift
+        flag_decisions="$(sanitize "${1:-}")"
+        ;;
+      --artifacts)
+        shift
+        flag_artifacts="$(sanitize "${1:-}")"
+        ;;
+      --next)
+        shift
+        flag_next="$(sanitize "${1:-}")"
+        ;;
+      --workflow-state)
+        shift
+        flag_workflow_state="$(sanitize_config_value "${1:-}")"
+        ;;
+      *)
+        # Ignore unknown flags for forward compatibility
+        ;;
+    esac
+    shift
+  done
+
+  # Build comment: header line always present
   local comment="Stage: ${completed} complete → ready for ${next}"
 
+  # Append structured fields only if provided
+  if [[ -n "$flag_summary" ]]; then
+    comment="${comment}
+Summary: ${flag_summary}"
+  fi
+  if [[ -n "$flag_decisions" ]]; then
+    comment="${comment}
+Decisions: ${flag_decisions}"
+  fi
+  if [[ -n "$flag_artifacts" ]]; then
+    comment="${comment}
+Artifacts: ${flag_artifacts}"
+  fi
+  if [[ -n "$flag_next" ]]; then
+    comment="${comment}
+Next: ${flag_next}"
+  fi
+  if [[ -n "$flag_workflow_state" ]]; then
+    comment="${comment}
+WorkflowState: ${flag_workflow_state}"
+  fi
+
   if ! bd_comment "$issue_id" "$comment" > /dev/null; then
     die "Failed to record stage transition on issue ${issue_id}"
   fi
@@ -269,6 +312,105 @@ cmd_stage_transition() {
   echo "Stage transition recorded on ${issue_id}: ${completed} → ${next}"
 }
 
+cmd_validate() {
+  if [[ $# -lt 1 ]]; then
+    echo "Usage: beads-context.sh validate <issue-id>" >&2
+    exit 1
+  fi
+
+  local issue_id="$1"
+  local warnings=0
+
+  # Get issue JSON
+  local json
+  json="$(bd show "$issue_id" --json 2>&1)" || {
+    echo "Error: Failed to retrieve issue ${issue_id}" >&2
+    exit 1
+  }
+
+  # Check for bd error patterns
+  if printf '%s' "$json" | grep -Eqi '^Error|Error resolving|Error fetching'; then
+    echo "Error: Issue not found: ${issue_id}" >&2
+    exit 1
+  fi
+
+  if [[ -z "$json" || "$json" == "[]" || "$json" == "null" ]]; then
+    echo "Error: Issue not found: ${issue_id}" >&2
+    exit 1
+  fi
+
+  # Extract fields — prefer jq, fall back to grep/sed
+  local description="" design=""
+  if command -v jq &>/dev/null; then
+    description="$(printf '%s' "$json" | jq -r 'if type == "array" then .[0].description else .description end // empty' 2>/dev/null || true)"
+    design="$(printf '%s' "$json" | jq -r 'if type == "array" then .[0].design else .design end // empty' 2>/dev/null || true)"
+  else
+    description="$(printf '%s' "$json" | grep -o '"description": *"[^"]*"' | head -1 | sed 's/^"description": *"//;s/"$//' || true)"
+    design="$(printf '%s' "$json" | grep -o '"design": *"[^"]*"' | head -1 | sed 's/^"design": *"//;s/"$//' || true)"
+  fi
+
+  # Check 1: Issue has description
+  if [[ -z "$description" ]]; then
+    echo "Warning: Issue ${issue_id} has no description"
+    warnings=$((warnings + 1))
+  fi
+
+  # Get comments to check for stage transitions
+  local comments
+  comments="$(bd comments list "$issue_id" 2>/dev/null || true)"
+
+  # Check 2: At least one stage transition exists
+  local has_transition=false
+  if echo "$comments" | grep -q 'Stage:.*complete'; then
+    has_transition=true
+  fi
+
+  if [[ "$has_transition" == "false" ]]; then
+    echo "Warning: No stage transition found on issue ${issue_id}"
+    warnings=$((warnings + 1))
+  fi
+
+  # Check 3: Most recent transition has summary
+  # Isolate the last transition block to avoid false-positives from earlier summaries
+  if [[ "$has_transition" == "true" ]]; then
+    local has_summary=false
+    local last_block
+    last_block="$(echo "$comments" | awk '/Stage:.*complete/{found=1; block=""} found{block=block"\n"$0} END{print block}')"
+    if echo "$last_block" | grep -q 'Summary:'; then
+      has_summary=true
+    fi
+    if [[ "$has_summary" == "false" ]]; then
+      echo "Warning: Most recent stage transition has no summary on issue ${issue_id}"
+      warnings=$((warnings + 1))
+    fi
+  fi
+
+  # Check 4: Design metadata is set if past plan stage
+  # "Past plan" means there's a transition FROM plan or any later stage
+  local past_plan=false
+  if echo "$comments" | grep -q 'Stage: plan complete'; then
+    past_plan=true
+  fi
+  if echo "$comments" | grep -Eq 'Stage: (dev|validate|ship|review|premerge) complete'; then
+    past_plan=true
+  fi
+
+  if [[ "$past_plan" == "true" && -z "$design" ]]; then
+    echo "Warning: Design metadata not set on issue ${issue_id} (past plan stage)"
+    warnings=$((warnings + 1))
+  fi
+
+  # Summary
+  if [[ $warnings -eq 0 ]]; then
+    echo "All context fields present on issue ${issue_id}"
+  else
+    echo "${warnings} warning(s) found on issue ${issue_id}"
+  fi
+
+  # Always exit 0 — advisory only
+  exit 0
+}
+
 # ── Main dispatcher ──────────────────────────────────────────────────────
 
 if [[ $# -lt 1 ]]; then
@@ -284,6 +426,7 @@ case "$subcommand" in
   update-progress)  cmd_update_progress "$@" ;;
   parse-progress)   cmd_parse_progress "$@" ;;
   stage-transition) cmd_stage_transition "$@" ;;
+  validate)         cmd_validate "$@" ;;
   *)
     echo "Error: Unknown subcommand '${subcommand}'" >&2
     usage

package/scripts/beads-context.test.js

@@ -8,10 +8,14 @@ const { resolveBashCommand } = require('../test/helpers/bash.js');
 const SCRIPT_PATH = path.join(__dirname, 'beads-context.sh');
 const WORKTREE_ROOT = path.resolve(__dirname, '..');
 
-// Check if bd CLI is available (not installed in CI)
+// Check if bd CLI is available AND Dolt database is reachable (not just binary exists).
+// Prevents tests from hanging when Dolt is dead. BD_TIMEOUT env var overrides default.
 function isBdAvailable() {
 	try {
 		execFileSync('bd', ['--version'], { stdio: 'ignore' });
+		// Also verify Dolt database is reachable (not just binary exists)
+		const timeout = parseInt(process.env.BD_TIMEOUT || '3000', 10);
+		execFileSync('bd', ['list', '--limit=1'], { stdio: 'ignore', timeout });
 		return true;
 	} catch {
 		return false;

package/scripts/check-agents.js

@@ -19,8 +19,110 @@
  */
 
 const { syncCommands } = require('./sync-commands');
+const { AGENT_ADAPTERS } = require('./sync-commands');
 const path = require('path');
 const fs = require('fs');
+const { validatePluginSchema } = require('../lib/plugin-manager');
+
+const SYNC_ADAPTER_BY_PLUGIN_ID = Object.freeze({
+  claude: 'claude-code',
+  cline: 'cline',
+  codex: 'codex',
+  copilot: 'github-copilot',
+  cursor: 'cursor',
+  kilocode: 'kilo-code',
+  opencode: 'opencode',
+  roo: 'roo-code',
+});
+
+function normalizeRelativeDir(dir) {
+  if (!dir) return null;
+  return String(dir).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+
+function getDeclaredCommandDir(plugin) {
+  const dirs = plugin.directories || {};
+  return dirs.commands || dirs.workflows || dirs.prompts || dirs.skills || null;
+}
+
+function getExpectedCommandDir(plugin) {
+  const adapterId = SYNC_ADAPTER_BY_PLUGIN_ID[plugin.id];
+  if (!adapterId) {
+    return null;
+  }
+
+  const adapter = AGENT_ADAPTERS[adapterId];
+  if (!adapter) {
+    return null;
+  }
+
+  if (plugin.id === 'codex') {
+    return normalizeRelativeDir(plugin.directories?.skills || adapter.baseDir);
+  }
+
+  return normalizeRelativeDir(adapter.baseDir);
+}
+
+function validatePluginParity(plugin, errors) {
+  const validation = validatePluginSchema(plugin);
+  if (!validation.valid) {
+    const parityErrors = validation.errors.filter((error) =>
+      error.startsWith('"support') || error.startsWith('"capabilities')
+    );
+    parityErrors.forEach((error) => {
+      errors.push(`Plugin "${plugin.name || plugin.id}" (${plugin.id || 'unknown'}): ${error}`);
+    });
+  }
+
+  const capabilities = plugin.capabilities || {};
+  const dirs = plugin.directories || {};
+  const supportStatus = plugin.support?.status;
+
+  if (capabilities.commands) {
+    const expectedDir = getExpectedCommandDir(plugin);
+    const declaredDir = normalizeRelativeDir(getDeclaredCommandDir(plugin));
+
+    if (!expectedDir) {
+      errors.push(
+        `Plugin "${plugin.name}" (${plugin.id}) declares commands support but has no Forge sync adapter.`
+      );
+    } else if (!declaredDir) {
+      errors.push(
+        `Plugin "${plugin.name}" (${plugin.id}) declares commands support but has no command directory configured.`
+      );
+    } else if (declaredDir !== expectedDir) {
+      errors.push(
+        `Plugin "${plugin.name}" (${plugin.id}) command directory "${declaredDir}" does not match sync output "${expectedDir}".`
+      );
+    }
+  }
+
+  if (capabilities.rules && !dirs.rules) {
+    errors.push(
+      `Plugin "${plugin.name}" (${plugin.id}) declares rules capability but has no scaffold path configured.`
+    );
+  }
+
+  if (capabilities.skills && !dirs.skills) {
+    errors.push(
+      `Plugin "${plugin.name}" (${plugin.id}) declares skills capability but has no scaffold path configured.`
+    );
+  }
+
+  if (supportStatus === 'deprecated' || supportStatus === 'unsupported') {
+    if (capabilities.skills) {
+      errors.push(
+        `Plugin "${plugin.name}" (${plugin.id}) is ${supportStatus} but still declares skills parity.`
+      );
+    }
+
+    if (plugin.setup?.createSkill || dirs.skills) {
+      errors.push(
+        `Plugin "${plugin.name}" (${plugin.id}) is ${supportStatus} but still scaffolds Forge skills.`
+      );
+    }
+  }
+}
 
 /**
  * Validate all agent configs are complete and in sync.
@@ -89,6 +191,7 @@ function checkAgents(repoRoot) {
       try {
         const plugin = JSON.parse(fs.readFileSync(path.join(pluginDir, file), 'utf8'));
         plugins.push(plugin);
+        validatePluginParity(plugin, errors);
       } catch (_err) {
         errors.push(`Failed to parse plugin file: lib/agents/${file}`);
       }

package/scripts/check-forge-token.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const path = require('node:path');
+
+const TOKEN_FILENAME = '.forge-push-token';
+const MAX_AGE_MS = 30000; // 30 seconds
+
+/**
+ * Get the absolute path to the token file.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string} Token file path
+ */
+function tokenPath(projectRoot) {
+  return path.join(projectRoot, TOKEN_FILENAME);
+}
+
+/**
+ * Write a one-time nonce token to disk.
+ * Called by `forge push` right before `git push` so lefthook hooks
+ * can detect that checks already passed and skip re-running them.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{nonce: string, timestamp: number}} The written token data
+ */
+function write(projectRoot) {
+  const data = {
+    nonce: crypto.randomUUID(),
+    timestamp: Date.now(),
+  };
+  fs.writeFileSync(tokenPath(projectRoot), JSON.stringify(data), 'utf-8');
+  return data;
+}
+
+/**
+ * Check if a valid (fresh, well-formed) forge push token exists.
+ * Does NOT delete the token — use `consume()` for one-time validation.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if a valid, fresh token exists
+ */
+function isValid(projectRoot) {
+  try {
+    const raw = fs.readFileSync(tokenPath(projectRoot), 'utf-8');
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Validate and delete the token in one atomic operation (one-time use).
+ * Always attempts to delete the file, even if the token is stale or invalid.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} True if the token was valid before deletion
+ */
+function consume(projectRoot) {
+  const tp = tokenPath(projectRoot);
+  try {
+    const raw = fs.readFileSync(tp, 'utf-8');
+    // Always delete after reading — whether valid or not
+    try { fs.unlinkSync(tp); } catch (_e) { /* already gone */ }
+
+    const content = JSON.parse(raw);
+    if (!content.nonce || typeof content.timestamp !== 'number') {
+      return false;
+    }
+    const age = Date.now() - content.timestamp;
+    return age < MAX_AGE_MS;
+  } catch (_err) {
+    // File doesn't exist or isn't readable — try cleanup anyway
+    try { fs.unlinkSync(tp); } catch (_e) { /* nothing to clean */ }
+    return false;
+  }
+}
+
+module.exports = { write, isValid, consume };
+
+// When run directly as a script (e.g., from lefthook skip check):
+// Exit 0 = token valid (skip hooks), Exit 1 = run hooks normally.
+// Uses isValid() (non-destructive) so multiple lefthook commands can
+// each check the same token. The token expires after 30s automatically.
+if (require.main === module) {
+  const projectRoot = process.cwd();
+  if (isValid(projectRoot)) {
+    console.log('forge push token valid — skipping pre-push hooks');
+    process.exit(0);
+  }
+  process.exit(1);
+}

package/scripts/conflict-detect.sh

@@ -19,12 +19,12 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Source file-index helpers (file_index_read, file_index_get)
-source "$SCRIPT_DIR/file-index.sh"
+source "$SCRIPT_DIR/file-index.sh" || { echo "FATAL: failed to source file-index.sh" >&2; exit 2; }
 
 # Source sync-utils (get_session_identity, sanitize_config_value)
 # Only source if available (tests may not need all utils)
 if [[ -f "$SCRIPT_DIR/sync-utils.sh" ]]; then
-  source "$SCRIPT_DIR/sync-utils.sh"
+  source "$SCRIPT_DIR/sync-utils.sh" || { echo "FATAL: failed to source sync-utils.sh" >&2; exit 2; }
 fi
 
 # ── Input Validation ─────────────────────────────────────────────────────

package/scripts/dep-guard.sh

@@ -12,6 +12,10 @@
 
 set -euo pipefail
 
+# Source shared sanitize library
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/sanitize.sh"
+
 # ── Helpers ──────────────────────────────────────────────────────────────
 
 usage() {
@@ -64,24 +68,6 @@ rollback_and_die() {
   die "$message"
 }
 
-# Sanitize a string: strip shell-injection patterns (OWASP A03)
-# Removes: double quotes, $(...), backticks, semicolons, and newlines
-sanitize() {
-  local val="$1"
-  # Remove double quotes
-  val="${val//\"/}"
-  # Remove $(...) command substitution patterns (loop handles nested)
-  # Use newline-separated commands for BSD sed compatibility (macOS)
-  val="$(printf '%s' "$val" | sed -e ':loop' -e 's/\$([^()]*)//g' -e 't loop')"
-  # Remove backtick command substitution
-  val="${val//\`/}"
-  # Remove semicolons (command chaining)
-  val="${val//;/}"
-  # Replace newlines with spaces
-  val="$(printf '%s' "$val" | tr '\n' ' ')"
-  printf '%s' "$val"
-}
-
 # Run bd update and check for errors in both exit code and output.
 # bd update exits 0 even for non-existent issues, so we check stdout too.
 bd_update() {
@@ -628,17 +614,9 @@ cmd_apply_decision() {
     die "Failed to add dependency ${dependent_issue} -> ${depends_on_issue}"
   }
 
-  local cycles_output
-  cycles_output="$(${BD_CMD:-bd} dep cycles 2>&1)" || {
-    rollback_dependency "$dependent_issue" "$depends_on_issue"
-    echo "$cycles_output" >&2
-    die "Failed to validate dependency cycles"
-  }
-
-  if printf '%s' "$cycles_output" | grep -Eqi 'cycle' \
-    && ! cycles_output_is_safe "$cycles_output"; then
+  # Check for cycles — use exit code as primary signal
+  if ! ${BD_CMD:-bd} dep cycles &>/dev/null; then
     rollback_dependency "$dependent_issue" "$depends_on_issue"
-    echo "$cycles_output" >&2
     die "Cycle detected for ${dependent_issue} -> ${depends_on_issue}"
   fi