forgedock 1.0.22 → 1.1.2

package/scripts/worktree-lifecycle.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# worktree-lifecycle.sh — Deterministic git worktree create/reuse/cleanup engine
+#
+# Usage:
+#   worktree-lifecycle.sh ensure <path> <branch> <base-ref>
+#   worktree-lifecycle.sh cleanup <path> <branch>
+#
+# Subcommands:
+#
+#   ensure <path> <branch> <base-ref>
+#     Idempotent worktree provisioning — replaces the LLM judgment call in
+#     work-on.md Phase 3E ("If worktree already exists: verify correct
+#     branch, reuse or remove and recreate.").
+#
+#       - No worktree registered at <path>:
+#           - Local branch <branch> already exists and is NOT checked out
+#             in another worktree  -> attach it at <path> (preserves any
+#             existing commits — covers the "worktree was lost but the
+#             branch survived" resume case).
+#           - Local branch <branch> already exists and IS checked out in
+#             another worktree      -> ERROR (exit 1). Two worktrees cannot
+#             share one branch; this needs human intervention, not silent
+#             repair.
+#           - Local branch <branch> does not exist
+#                                    -> git worktree add <path> -b <branch> <base-ref>
+#       - A worktree is already registered at <path>:
+#           - already on <branch>   -> reuse, no destructive action (OK).
+#           - on a different branch -> git worktree remove <path> --force,
+#                                       then re-run the "no worktree" logic above.
+#
+#   cleanup <path> <branch>
+#     Removes the worktree at <path> (tolerant of already-removed state)
+#     and force-deletes the local branch <branch> (tolerant of
+#     already-deleted state). Matches work-on.md Phase 6E exactly.
+#
+# Exit codes:
+#   0 = success (worktree ensured / cleaned up, including no-op reuse)
+#   1 = error (bad args, branch already checked out elsewhere, git failure)
+#
+# Notes:
+#   - Must be invoked from inside the target git repository (any worktree
+#     of it — main or linked) OR with <path> pointing at an existing
+#     worktree of it. `git worktree`/`git branch` subcommands operate on
+#     the whole repository regardless of which worktree anchors the `-C`.
+#
+# Examples:
+#   worktree-lifecycle.sh ensure /repo/.claude/worktrees/fix-123 fix/thing-123 origin/staging
+#   worktree-lifecycle.sh cleanup /repo/.claude/worktrees/fix-123 fix/thing-123
+
+set -euo pipefail
+
+# Export universal script environment so per-repo adaptive scripts can
+# delegate back into universal scripts (see devdocs/project/architecture.md
+# → Script Precedence).
+export FORGEDOCK_SCRIPTS
+FORGEDOCK_SCRIPTS="$(cd "$(dirname "$0")" && pwd)"
+export FORGEDOCK_HOME
+FORGEDOCK_HOME="$(cd "$(dirname "$0")/.." && pwd)"
+
+usage() {
+  echo "Usage:" >&2
+  echo "  worktree-lifecycle.sh ensure <path> <branch> <base-ref>" >&2
+  echo "  worktree-lifecycle.sh cleanup <path> <branch>" >&2
+}
+
+# ---------------------------------------------------------------------------
+# resolve_repo_anchor [fallback_path]
+#
+# Returns a directory suitable for `git -C <dir> worktree ...` /
+# `git -C <dir> branch ...` — any directory inside the repository works,
+# main or linked worktree alike, as long as it stays valid for the whole
+# operation. Prefers the invoking cwd (matches the calling convention used
+# throughout work-on.md — callers `cd {REPO_PATH}` before invoking scripts)
+# so the anchor is never the same path that `ensure`/`cleanup` may remove
+# mid-operation. Only falls back to `fallback_path` (e.g. the target
+# worktree itself) when cwd is not inside a git repo at all.
+# ---------------------------------------------------------------------------
+resolve_repo_anchor() {
+  local fallback="${1:-}"
+  if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    pwd
+    return 0
+  fi
+  if [ -n "$fallback" ] && [ -d "$fallback" ] && git -C "$fallback" rev-parse --show-toplevel >/dev/null 2>&1; then
+    echo "$fallback"
+    return 0
+  fi
+  echo "ERROR: not inside a git repository, and '$fallback' is not a valid worktree to anchor to" >&2
+  exit 1
+}
+
+if [ "$#" -lt 1 ]; then
+  echo "ERROR: subcommand required (ensure|cleanup)" >&2
+  usage
+  exit 1
+fi
+
+SUBCOMMAND="$1"
+shift
+
+case "$SUBCOMMAND" in
+  ensure)
+    if [ "$#" -ne 3 ]; then
+      echo "ERROR: ensure requires exactly 3 arguments: <path> <branch> <base-ref>" >&2
+      usage
+      exit 1
+    fi
+    WT_PATH="$1"
+    BRANCH="$2"
+    BASE_REF="$3"
+
+    if [ -z "$WT_PATH" ] || [ -z "$BRANCH" ] || [ -z "$BASE_REF" ]; then
+      echo "ERROR: <path>, <branch>, and <base-ref> must all be non-empty" >&2
+      exit 1
+    fi
+
+    ANCHOR=$(resolve_repo_anchor "$WT_PATH")
+
+    # -----------------------------------------------------------------
+    # attach_or_create <path> <branch> <base-ref>
+    # Assumes no worktree is currently registered at <path>.
+    # -----------------------------------------------------------------
+    attach_or_create() {
+      local path="$1" branch="$2" base_ref="$3"
+
+      if git -C "$ANCHOR" show-ref --verify --quiet "refs/heads/$branch"; then
+        local existing_wt
+        existing_wt=$(git -C "$ANCHOR" worktree list --porcelain | awk -v b="refs/heads/$branch" '
+            /^worktree /{wt=$2}
+            /^branch /{if ($2==b) print wt}
+          ')
+        if [ -n "$existing_wt" ]; then
+          echo "ERROR: branch '$branch' is already checked out in worktree '$existing_wt' — cannot attach it at '$path'" >&2
+          echo "       Resolve manually: remove the stale worktree, or choose a different branch/path." >&2
+          exit 1
+        fi
+        echo "Branch '$branch' exists locally — attaching it at '$path' (preserving existing commits)..."
+        git -C "$ANCHOR" worktree add -- "$path" "$branch"
+      else
+        echo "Creating new branch '$branch' from '$base_ref' at '$path'..."
+        git -C "$ANCHOR" worktree add -b "$branch" -- "$path" "$base_ref"
+      fi
+      echo "OK: worktree ready at '$path' on branch '$branch'"
+    }
+
+    ABS_WT_PATH=$(realpath -m "$WT_PATH")
+    REGISTERED=$(git -C "$ANCHOR" worktree list --porcelain | awk -v p="$ABS_WT_PATH" '
+        /^worktree /{if ($2==p) print $2}
+      ')
+
+    if [ -z "$REGISTERED" ]; then
+      # No worktree registered at this path per git. If a stray non-worktree
+      # directory already exists there, fail loud rather than silently
+      # clobbering unrelated content.
+      if [ -e "$WT_PATH" ] && [ ! -e "$WT_PATH/.git" ]; then
+        echo "ERROR: '$WT_PATH' exists but is not a registered git worktree — refusing to overwrite it" >&2
+        exit 1
+      fi
+      attach_or_create "$WT_PATH" "$BRANCH" "$BASE_REF"
+    else
+      CURRENT_BRANCH=$(git -C "$REGISTERED" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+      if [ "$CURRENT_BRANCH" = "$BRANCH" ]; then
+        echo "OK: worktree at '$REGISTERED' already on branch '$BRANCH' — reusing (no action)"
+      else
+        echo "Worktree at '$REGISTERED' is on branch '${CURRENT_BRANCH:-<detached>}', expected '$BRANCH' — removing and recreating..."
+        git -C "$ANCHOR" worktree remove "$REGISTERED" --force
+        attach_or_create "$WT_PATH" "$BRANCH" "$BASE_REF"
+      fi
+    fi
+    ;;
+
+  cleanup)
+    if [ "$#" -ne 2 ]; then
+      echo "ERROR: cleanup requires exactly 2 arguments: <path> <branch>" >&2
+      usage
+      exit 1
+    fi
+    WT_PATH="$1"
+    BRANCH="$2"
+
+    if [ -z "$WT_PATH" ] || [ -z "$BRANCH" ]; then
+      echo "ERROR: <path> and <branch> must both be non-empty" >&2
+      exit 1
+    fi
+
+    ANCHOR=$(resolve_repo_anchor "$WT_PATH")
+
+    echo "Removing worktree at '$WT_PATH' (if present)..."
+    git -C "$ANCHOR" worktree remove "$WT_PATH" --force 2>/dev/null || true
+
+    echo "Deleting local branch '$BRANCH' (if present)..."
+    git -C "$ANCHOR" branch -D -- "$BRANCH" 2>/dev/null || true
+
+    echo "OK: cleanup complete for '$WT_PATH' / '$BRANCH'"
+    ;;
+
+  *)
+    echo "ERROR: unknown subcommand '$SUBCOMMAND' (expected: ensure|cleanup)" >&2
+    usage
+    exit 1
+    ;;
+esac

package/templates/devdocs/agent/using-forgedock.md

@@ -228,6 +228,20 @@ When `forge.yaml → repos.satellites` is configured, issue numbers can be prefi
 
 ---
 
+## Spec Compliance Rules
+
+Command specs declare constraints that agents MUST follow. These rules are not enforced at the tool-call level — compliance depends entirely on the agent reading and obeying the spec. Violations are invisible to the pipeline and can silently skip critical safety gates.
+
+1. **Respect `allowed-tools` frontmatter.** When a command spec declares `allowed-tools:` in its YAML frontmatter, NEVER use a tool not in that list. In particular, NEVER use the `Agent` tool when it is not listed — use `Task` or `Skill` instead. The `Agent` tool spawns opaque subprocesses that bypass `allowed-tools` constraints and cannot post structured output.
+
+2. **Execute Phase 0 routing before any other phase.** Commands with Phase 0 routing conditions (e.g., `review-pr.md` routing staging PRs to `review-pr-staging`) MUST evaluate the routing check before proceeding. Skipping routing can bypass entire sub-pipelines including deploy gates, test gates, and structured finding creation.
+
+3. **Look for `FORGE:SPEC_LOADED` markers.** Critical command specs include a `<!-- FORGE:SPEC_LOADED -->` HTML comment near the top. If you are executing a command and do not see this marker in your context, the spec was not loaded — stop and re-read the command file before proceeding.
+
+<!-- Added: forge#1383 — agent spec-compliance enforcement -->
+
+---
+
 ## Idempotency Rules
 
 - Re-invoking `/work-on` on a completed issue is safe — it reads the terminal label and stops