@warpgogol/forge 2.21.8 → 4.0.0

package/AGENTS.md

@@ -81,6 +81,18 @@ The pinned-files protection system prevents accidental deletion, move, or modifi
 - **Archive pre-check:** All 6 archive handlers (`rfc.archive`, `adr.archive`, `plan.archive`, `audit.archive`, `session.archive`, `mission.archive`) load the pinned manifest once per invocation and skip pinned files/directories with a warning instead of moving them. When the manifest is missing, archive handlers behave as before (protection inactive). **Intra-directory moves are exempted:** if both source and destination are within the same pinned directory (e.g. `docs/rfcs/rfc-0076.md` → `docs/rfcs/archive/implemented/rfc-0076.md`), the move is allowed — the file hasn't left the protected directory.
 - **`.forge/` directory:** The `.forge/` directory is a forge-specific convention for project-local governance files. It sits alongside `forge.yaml` and contains `pinned.yaml` (manifest) and `pinned-audit.log` (override audit trail).
 
+## Agent-safety scripts in profiles (RFC-1019)
+
+All Forge stack profiles include portable agent-safety scripts as embedded file content blocks. These scripts protect AI agents from destructive git operations and enforce session-end protocol.
+
+- **`scripts/git-guard.sh`** — shell function intercepting `git stash`, `git reset --hard`, `git checkout --`, `git checkout -f`, `git switch -f`, `git clean -f`, `git restore`. Override: `ALLOW_DESTRUCTIVE_GIT=1`. Uses `FORGE_GIT_GUARD` marker (not `WERKSTATT_GIT_GUARD`).
+- **`scripts/setup-git-guards.sh`** — installs git-guard.sh into `~/.zshenv`. Supports `install`, `--verify`, `--remove` modes.
+- **`scripts/clean-stale-stashes.sh`** — detects and optionally drops stale git stash entries. Report mode (`--drop` to clean, `--drop-all` for all).
+- **`scripts/check-clean-trees.sh`** — universal dirty-tree checker. Finds all `.git` directories up to 3 levels deep and checks each for dirty state.
+- **`hooks/pre-user-prompt.sh`** — session-end protocol enforcement + stale-stash detection + git-guard verification. Requires `jq`. Exits with code 2 on session-end trigger phrases to inject protocol instructions.
+- **`.windsurf/hooks.json`** — Windsurf hook registration for `pre_user_prompt`.
+- **PREFERENCES.md** generated by `forge init` includes `formOfAddress` field and operational rules: plan confirmation vs implementation, skill invocation tracking, commit granularity, session-end protocol.
+
 ## Skills
 
 Skills live in `skills/` and are synced to `.agents/skills/` by `create`. Each skill has a `SKILL.md` with standardized frontmatter (name, description, category, concerns, dependsOn).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.21.8",
+  "version": "4.0.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/forge-shell.yaml

@@ -220,6 +220,314 @@ workspace:
         # Runs forge validation before commits
         echo "Pre-commit: running platform checks..."
         pnpm exec forge run forge.validate || exit 1
+    - path: scripts/git-guard.sh
+      content: |
+        #!/bin/bash
+        # git-guard.sh — shell function that intercepts destructive git commands.
+        # Sourced by ~/.zshenv (via setup-git-guards.sh).
+        # Guards (only active in repos containing scripts/git-guard.sh):
+        #   git stash, git reset --hard, git checkout --, git checkout -f,
+        #   git switch -f, git clean -f, git restore
+        # Override: ALLOW_DESTRUCTIVE_GIT=1 git stash
+
+        export FORGE_GIT_GUARD=1
+
+        _git_guard_find_root() {
+          local _repo_root _dir
+          _repo_root="$(command git rev-parse --show-toplevel 2>/dev/null || echo "")"
+          if [ -z "$_repo_root" ]; then echo ""; return; fi
+          if [ -f "$_repo_root/scripts/git-guard.sh" ]; then echo "$_repo_root"; return; fi
+          _dir="$(dirname "$_repo_root")"
+          while [ -n "$_dir" ] && [ "$_dir" != "/" ]; do
+            if [ -f "$_dir/scripts/git-guard.sh" ]; then echo "$_dir"; return; fi
+            _dir="$(dirname "$_dir")"
+          done
+          echo ""
+        }
+
+        git() {
+          local _guard_root
+          _guard_root="$(_git_guard_find_root)"
+          if [ -z "$_guard_root" ] || [ -n "${ALLOW_DESTRUCTIVE_GIT:-}" ]; then
+            command git "$@"; return $?
+          fi
+          local _all_args=("$@") _i=0 _cmd="" _cmd_index=0
+          while [ "$_i" -lt "${#_all_args[@]}" ]; do
+            local _arg="${_all_args[$_i]}"
+            case "$_arg" in
+              -C|-c|--git-dir|--work-tree|--namespace) _i=$((_i + 2)); continue ;;
+              -*) _i=$((_i + 1)); continue ;;
+            esac
+            _cmd="$_arg"; _cmd_index="$_i"; break
+          done
+          local _sub_args=() _j=$((_cmd_index + 1))
+          while [ "$_j" -lt "${#_all_args[@]}" ]; do
+            _sub_args+=("${_all_args[$_j]}"); _j=$((_j + 1))
+          done
+          case "$_cmd" in
+            stash)
+              echo "BLOCKED: git stash is disabled in agent sessions." >&2
+              echo "Set ALLOW_DESTRUCTIVE_GIT=1 to override." >&2; return 1 ;;
+            reset)
+              for _arg in "${_sub_args[@]}"; do
+                if [ "$_arg" = "--hard" ] || [[ "$_arg" == --hard=* ]]; then
+                  echo "BLOCKED: git reset --hard is disabled." >&2; return 1
+                fi
+              done; command git "$@"; return $? ;;
+            checkout)
+              for _arg in "${_sub_args[@]}"; do
+                if [ "$_arg" = "--" ]; then
+                  echo "BLOCKED: git checkout -- is disabled." >&2; return 1
+                fi
+                case "$_arg" in -f*|--force*)
+                  echo "BLOCKED: git checkout -f is disabled." >&2; return 1 ;;
+                esac
+              done; command git "$@"; return $? ;;
+            switch)
+              for _arg in "${_sub_args[@]}"; do
+                case "$_arg" in -f*|--force*)
+                  echo "BLOCKED: git switch -f is disabled." >&2; return 1 ;;
+                esac
+              done; command git "$@"; return $? ;;
+            restore)
+              echo "BLOCKED: git restore is disabled." >&2; return 1 ;;
+            clean)
+              for _arg in "${_sub_args[@]}"; do
+                case "$_arg" in -f*|--force*)
+                  echo "BLOCKED: git clean -f is disabled." >&2; return 1 ;;
+                esac
+              done; command git "$@"; return $? ;;
+            *) command git "$@"; return $? ;;
+          esac
+        }
+    - path: scripts/setup-git-guards.sh
+      content: |
+        #!/bin/bash
+        # setup-git-guards.sh — install shell function guards for destructive git ops.
+        # Auto-detects shell: zsh → ~/.zshenv, bash → ~/.bashrc (Git Bash on Windows).
+        set -euo pipefail
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+        if [ -z "$repo_root" ]; then echo "ERROR: not inside a git repository" >&2; exit 1; fi
+        guard_script="$repo_root/scripts/git-guard.sh"
+        marker="# forge-git-guard"
+        # Auto-detect target profile file based on current shell
+        case "${SHELL:-}" in
+          *zsh*) profile_file="${HOME}/.zshenv" ;;
+          *bash*) profile_file="${HOME}/.bashrc" ;;
+          *) profile_file="${HOME}/.bashrc" ;;
+        esac
+        mode="${1:-install}"
+        case "$mode" in
+          install)
+            if [ ! -f "$guard_script" ]; then echo "ERROR: $guard_script not found" >&2; exit 1; fi
+            chmod +x "$guard_script" 2>/dev/null || true
+            if [ -f "$profile_file" ]; then
+              tmp="$(mktemp)"
+              awk -v marker="$marker" '$0 == marker { skip=2; next } skip > 0 { skip--; next } { print }' "$profile_file" > "$tmp" || true
+              mv "$tmp" "$profile_file" 2>/dev/null || true
+            fi
+            echo "" >> "$profile_file"
+            echo "$marker" >> "$profile_file"
+            echo "[ -f \"$guard_script\" ] && source \"$guard_script\"" >> "$profile_file"
+            echo "Git guards installed into $profile_file. Restart your shell or run: source $guard_script" ;;
+          --verify)
+            if [ -z "${FORGE_GIT_GUARD:-}" ]; then echo "MISSING: git guard not loaded" >&2; exit 1; fi
+            if ! grep -qF "$marker" "$profile_file" 2>/dev/null; then echo "MISSING: guard not in $profile_file" >&2; exit 1; fi
+            echo "OK: git guards installed and loaded" ;;
+          --remove)
+            if [ -f "$profile_file" ]; then
+              tmp="$(mktemp)"
+              awk -v marker="$marker" '$0 == marker { skip=2; next } skip > 0 { skip--; next } { print }' "$profile_file" > "$tmp" || true
+              mv "$tmp" "$profile_file" 2>/dev/null || true
+            fi
+            echo "Git guards removed from $profile_file" ;;
+          *) echo "Usage: bash scripts/setup-git-guards.sh [install|--verify|--remove]" >&2; exit 1 ;;
+        esac
+    - path: scripts/clean-stale-stashes.sh
+      content: |
+        #!/bin/bash
+        # clean-stale-stashes.sh — detect and optionally drop stale git stash entries.
+        # Usage: bash scripts/clean-stale-stashes.sh [--drop|--drop-all]
+        set -euo pipefail
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+        if [ -z "$repo_root" ]; then echo "ERROR: not inside a git repository" >&2; exit 1; fi
+        mode="report"
+        if [ "${1:-}" = "--drop" ]; then mode="drop"; elif [ "${1:-}" = "--drop-all" ]; then mode="drop-all"; fi
+        stash_count="$(git -C "$repo_root" stash list 2>/dev/null | wc -l)"
+        if [ "$stash_count" -eq 0 ]; then exit 0; fi
+        stale_indices=() total="$stash_count"
+        for ((i = 0; i < total; i++)); do
+          ref="stash@{$i}"
+          if [ "$mode" = "drop-all" ]; then stale_indices+=("$i"); continue; fi
+          tracked_changes="$(git -C "$repo_root" stash show "$ref" --stat 2>/dev/null || true)"
+          untracked_files="$(git -C "$repo_root" stash show --include-untracked "$ref" --stat 2>/dev/null || true)"
+          if [ -z "$tracked_changes" ] && [ -z "$untracked_files" ]; then stale_indices+=("$i"); continue; fi
+          if [ -z "$tracked_changes" ] && [ -n "$untracked_files" ]; then
+            all_committed=true
+            while IFS= read -r filepath; do
+              [ -z "$filepath" ] && continue
+              if ! git -C "$repo_root" cat-file -e "HEAD:$filepath" 2>/dev/null; then all_committed=false; break; fi
+            done < <(git -C "$repo_root" stash show --include-untracked "$ref" --name-only 2>/dev/null || true)
+            if [ "$all_committed" = true ]; then stale_indices+=("$i"); fi
+          fi
+        done
+        if [ ${#stale_indices[@]} -eq 0 ]; then exit 0; fi
+        if [ "$mode" = "report" ]; then
+          echo "STALE STASH ENTRIES DETECTED (${#stale_indices[@]} of $stash_count):"
+          for idx in "${stale_indices[@]}"; do
+            echo "  stash@{$idx}: $(git -C "$repo_root" stash list | sed -n "$((idx + 1))p")"
+          done
+          echo "Clean with: bash scripts/clean-stale-stashes.sh --drop"; exit 1
+        fi
+        if [ "$mode" = "drop-all" ]; then git -C "$repo_root" stash clear; echo "Dropped all $stash_count entries."; exit 0; fi
+        for ((i = ${#stale_indices[@]} - 1; i >= 0; i--)); do
+          idx="${stale_indices[$i]}"
+          git -C "$repo_root" stash drop "stash@{$idx}" 2>/dev/null || true
+        done
+        echo "Dropped ${#stale_indices[@]} stale entry/entries."; exit 0
+    - path: scripts/check-clean-trees.sh
+      content: |
+        #!/bin/bash
+        # check-clean-trees.sh — verify all git trees are clean.
+        # Checks repo root + all nested .git directories up to 3 levels deep.
+        set -euo pipefail
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+        if [ -z "$repo_root" ]; then echo "ERROR: not inside a git repository" >&2; exit 1; fi
+        dirty=0 output=""
+        main_status="$(git -C "$repo_root" status --short 2>/dev/null || true)"
+        if [ -n "$main_status" ]; then
+          output+="DIRTY: $repo_root\n$(printf '%s\n' "$main_status" | sed 's/^/  /')\n"
+          dirty=1
+        fi
+        while IFS= read -r gitdir; do
+          nested_root="$(dirname "$gitdir")"
+          [ "$nested_root" = "$repo_root" ] && continue
+          nested_status="$(git -C "$nested_root" status --short 2>/dev/null || true)"
+          if [ -n "$nested_status" ]; then
+            output+="DIRTY: $nested_root\n$(printf '%s\n' "$nested_status" | sed 's/^/  /')\n"
+            dirty=1
+          fi
+        done < <(find "$repo_root" -maxdepth 3 -name ".git" -type d 2>/dev/null | head -20)
+        if [ "$dirty" -eq 1 ]; then
+          echo -e "$output" | head -40
+          echo "---"
+          echo "Uncommitted changes detected. Commit before session end."
+          exit 1
+        fi
+        exit 0
+    - path: hooks/pre-user-prompt.sh
+      content: |
+        #!/bin/bash
+        # Pre-user-prompt hook: session-end protocol + stale-stash + git-guard checks.
+        # Requires jq for JSON payload parsing.
+        set -euo pipefail
+        payload="$(cat)"
+        user_prompt="$(printf '%s' "$payload" | jq -r '.tool_info.user_prompt // empty' 2>/dev/null || true)"
+        if [ -z "$user_prompt" ]; then exit 0; fi
+        repo_root="$(git rev-parse --show-toplevel 2>/dev/null || echo "")"
+        if [ -n "$repo_root" ] && [ -x "$repo_root/scripts/clean-stale-stashes.sh" ]; then
+          stash_output="$("$repo_root/scripts/clean-stale-stashes.sh" 2>&1 || true)"
+          if [ -n "$stash_output" ]; then
+            echo "⚠️  STALE GIT STASH DETECTED" >&2
+            echo "$stash_output" >&2
+            echo "Clean with: bash scripts/clean-stale-stashes.sh --drop" >&2
+            echo "" >&2
+          fi
+        fi
+        if [ -n "$repo_root" ] && [ -f "$repo_root/scripts/git-guard.sh" ]; then
+          if [ -z "${FORGE_GIT_GUARD:-}" ]; then
+            echo "⚠️  GIT GUARD NOT LOADED — destructive git operations are NOT blocked." >&2
+            echo "Run: source $repo_root/scripts/git-guard.sh" >&2
+            echo "" >&2
+          fi
+        fi
+        session_end_phrases=("Завершаем эту сессию" "Завершаем сессию" "Заканчиваем сессию" "Завершить сессию" "End session" "Wrap up" "Session end" "/session-end")
+        matched=""
+        for phrase in "${session_end_phrases[@]}"; do
+          if printf '%s' "$user_prompt" | grep -qiF "$phrase"; then matched="$phrase"; break; fi
+        done
+        if [ -z "$matched" ]; then exit 0; fi
+        cat >&2 <<EOF
+        SESSION-END PROTOCOL TRIGGERED (matched: "$matched")
+        The user's original message was:
+          > $user_prompt
+        You MUST invoke the fo-session-retro skill via the skill tool BEFORE producing
+        any other output. This is a NON-NEGOTIABLE BLOCKED GATE per PREFERENCES.md.
+        DO NOT produce a closing summary or ad-hoc output. The closing block must come
+        from fo-session-retro's report.
+        Protocol steps:
+        1. Verify clean working trees — run: bash scripts/check-clean-trees.sh
+        2. Invoke fo-session-retro via the skill tool
+        3. The retro skill's report IS the session-end output
+        EOF
+        if [ -n "$repo_root" ] && [ -x "$repo_root/scripts/check-clean-trees.sh" ]; then
+          tree_output="$("$repo_root/scripts/check-clean-trees.sh" 2>&1 || true)"
+          if [ -n "$tree_output" ]; then echo "" >&2; echo "$tree_output" >&2; fi
+        fi
+        exit 2
+    - path: hooks/pre-user-prompt-wrapper.mjs
+      content: |
+        #!/usr/bin/env node
+        // pre-user-prompt-wrapper.mjs — cross-platform wrapper for pre-user-prompt.sh.
+        // Detects bash availability, prints one-time warning if bash not found,
+        // then delegates to bash hooks/pre-user-prompt.sh with stdin piped.
+        import { execFileSync, spawn } from "node:child_process";
+        import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+        import { dirname, join } from "node:path";
+        import { fileURLToPath } from "node:url";
+
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const scriptPath = join(__dirname, "pre-user-prompt.sh");
+        const cacheDir = join(__dirname, "..", ".cache");
+        const warningFlag = join(cacheDir, "git-guard-warning-sent");
+
+        // If pre-user-prompt.sh doesn't exist, silently exit
+        if (!existsSync(scriptPath)) {
+          process.exit(0);
+        }
+
+        // Check if bash is available
+        let bashAvailable = false;
+        try {
+          execFileSync("bash", ["--version"], { stdio: "ignore" });
+          bashAvailable = true;
+        } catch {
+          bashAvailable = false;
+        }
+
+        if (!bashAvailable) {
+          // Print one-time warning if not already sent
+          if (!existsSync(warningFlag)) {
+            console.error("⚠️  bash not found — pre-user-prompt hook is disabled.");
+            console.error("Install Git Bash (Git for Windows) or WSL to enable agent-safety hooks.");
+            console.error("");
+            try {
+              mkdirSync(cacheDir, { recursive: true });
+              writeFileSync(warningFlag, new Date().toISOString(), "utf8");
+            } catch {
+              // Best-effort — don't crash if cache dir is not writable
+            }
+          }
+          process.exit(0);
+        }
+
+        // Delegate to bash script with stdin piped
+        const child = spawn("bash", [scriptPath], { stdio: ["inherit", "inherit", "inherit"] });
+        child.on("exit", (code) => {
+          process.exit(code ?? 0);
+        });
+    - path: .windsurf/hooks.json
+      content: |
+        {
+          "hooks": {
+            "pre_user_prompt": [
+              {
+                "command": "node $ROOT_WORKSPACE_PATH/hooks/pre-user-prompt-wrapper.mjs",
+                "show_output": true
+              }
+            ]
+          }
+        }
     - path: systems-cache/.gitkeep
       content: |
         # Sternsystem cache directory (RFC-0790)
@@ -243,6 +551,14 @@ workspace:
             mode: protect
           - path: systems-cache/.gitkeep
             mode: protect
+          - path: scripts/git-guard.sh
+            mode: protect
+          - path: scripts/setup-git-guards.sh
+            mode: protect
+          - path: hooks/pre-user-prompt.sh
+            mode: protect
+          - path: hooks/pre-user-prompt-wrapper.mjs
+            mode: protect
     - path: README.md
       content: |
         # __PROJECT_NAME__
@@ -253,6 +569,8 @@ workspace:
 
         - Node.js 24+
         - pnpm 10+
+        - jq (for pre-user-prompt hook)
+        - On Windows: Git Bash or WSL (for shell scripts)
 
         ## Setup
 
@@ -270,7 +588,19 @@ workspace:
         pnpm install
         ```
 
-        ### 3. Verify the workshop
+        ### 3. Install git guards (recommended)
+
+        Git guards prevent AI agents from running destructive git commands (`git stash`, `git reset --hard`, `git checkout --`, `git restore`, `git clean -f`):
+
+        ```sh
+        bash scripts/setup-git-guards.sh
+        ```
+
+        This installs a shell function into your shell profile (`~/.zshenv` for zsh, `~/.bashrc` for bash/Git Bash). Restart your shell or run `source scripts/git-guard.sh`.
+
+        > **Windows**: Git guards require Git Bash (included with Git for Windows). Run `bash scripts/setup-git-guards.sh` from Git Bash. If bash is not in PATH, the pre-user-prompt hook wrapper prints a one-time warning. Install `jq` via `winget install jqlang.jq` or `choco install jq`.
+
+        ### 4. Verify the workshop
 
         ```sh
         pnpm exec forge run forge.doctor