Ubs

# SQLite databases
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm

# Daemon runtime files
.write.lock
daemon.lock
daemon.log
daemon-*.log
daemon-*.log.gz
daemon.pid
bd.sock

# Local version tracking (prevents upgrade notification spam after git ops)
.local_version

# Legacy database files
db.sqlite
bd.db

# Merge artifacts (temporary files from 3-way merge)
beads.base.jsonl
beads.base.meta.json
beads.left.jsonl
beads.left.meta.json
beads.right.jsonl
beads.right.meta.json
*.migrated

# Keep JSONL exports and config (source of truth for git)
!issues.jsonl
!metadata.json
!config.json

# Local history backups
.br_history/

# bv (beads viewer) lock file
.bv.lock

sync-branch: beads-sync
issue_prefix: ultimate_bug_scanner

{"id":"ultimate_bug_scanner-install-ast-grep-required"}
{"id":"ultimate_bug_scanner-js-ts-degraded-mode-contract"}
{"id":"ultimate_bug_scanner-tests-js-env-error-no-ast2"}
{"id":"ultimate_bug_scanner-xkw"}
{"id":"ultimate_bug_scanner-mep"}
{"id":"ultimate_bug_scanner-js-fail-fast-without-ast2"}
{"id":"ultimate_bug_scanner-ubs-env-error-exitcode"}
{"id":"ultimate_bug_scanner-js-module-env-ast-grep-bin2"}
{"id":"ultimate_bug_scanner-ank"}
{"id":"ultimate_bug_scanner-iua"}
{"id":"ultimate_bug_scanner-js-global-pollution-fp-fix2"}

{
  "database": "beads.db",
  "jsonl_export": "issues.jsonl"
}

#!/usr/bin/env python3
"""
Git/filesystem safety guard for Claude Code.

Blocks destructive commands that can lose uncommitted work or delete files.
This hook runs before Bash commands execute and can deny dangerous operations.

Exit behavior:
  - Exit 0 with JSON {"hookSpecificOutput": {"permissionDecision": "deny", ...}} = block
  - Exit 0 with no output = allow
"""
import json
import os
import re
import shlex
import sys

# Destructive patterns to block - tuple of (regex, reason)
DESTRUCTIVE_PATTERNS = [
    # Git commands that discard uncommitted changes
    (
        r"git\s+checkout\s+--\s+",
        "git checkout -- discards uncommitted changes permanently. Use 'git stash' first."
    ),
    (
        r"git\s+checkout\s+(?!-b\b)(?!--orphan\b)[^\s]+\s+--\s+",
        "git checkout <ref> -- <path> overwrites working tree. Use 'git stash' first."
    ),
    (
        r"git\s+restore\s+(?!--staged\b)[^\s]*\s*$",
        "git restore discards uncommitted changes. Use 'git stash' or 'git diff' first."
    ),
    (
        r"git\s+restore\s+--worktree",
        "git restore --worktree discards uncommitted changes permanently."
    ),
    # Git reset variants
    (
        r"git\s+reset\s+--hard",
        "git reset --hard destroys uncommitted changes. Use 'git stash' first."
    ),
    (
        r"git\s+reset\s+--merge",
        "git reset --merge can lose uncommitted changes."
    ),
    # Git clean
    (
        r"git\s+clean\s+-[a-z]*f",
        "git clean -f removes untracked files permanently. Review with 'git clean -n' first."
    ),
    # Force operations
    (
        r"git\s+push\s+.*--force(?!-with-lease)",
        "Force push can destroy remote history. Use --force-with-lease if necessary."
    ),
    (
        r"git\s+push\s+-f\b",
        "Force push (-f) can destroy remote history. Use --force-with-lease if necessary."
    ),
    (
        r"git\s+branch\s+-D\b",
        "git branch -D force-deletes without merge check. Use -d for safety."
    ),
    # Destructive filesystem commands
    (
        r"rm\s+-[a-z]*r[a-z]*f|rm\s+-[a-z]*f[a-z]*r",
        "rm -rf is destructive. List files first, then delete individually with permission."
    ),
    (
        r"rm\s+-rf\s+[/~]",
        "rm -rf on root or home paths is extremely dangerous."
    ),
    # Git stash drop/clear without explicit permission
    (
        r"git\s+stash\s+drop",
        "git stash drop permanently deletes stashed changes. List stashes first."
    ),
    (
        r"git\s+stash\s+clear",
        "git stash clear permanently deletes ALL stashed changes."
    ),
]

RM_RF_ALLOWED_PREFIXES = (
    os.path.join(os.sep, "tmp", ""),
    os.path.join(os.sep, "var", "tmp", ""),
    "${TMPDIR:-/tmp}/",
    "${TMPDIR:-/var/tmp}/",
)

RM_SEPARATORS = {"&&", "||", ";", "|"}


def _is_rm_command(token: str) -> bool:
    """Check if a token is the rm command (handles full paths like /bin/rm)."""
    if token == "rm":
        return True
    # Handle absolute paths: /bin/rm, /usr/bin/rm, etc.
    if token.endswith("/rm"):
        return True
    return False


def has_rm_recursive_force(command: str) -> bool:
    """Check if command contains rm with both recursive and force flags.

    Handles all variants:
    - rm -rf, rm -fr (combined short flags)
    - rm -r -f, rm -f -r (separate short flags)
    - rm --recursive --force (long flags)
    - rm -r --force, rm --recursive -f (mixed)
    """
    try:
        tokens = shlex.split(command, posix=True)
    except ValueError:
        return False

    i = 0
    while i < len(tokens):
        if not _is_rm_command(tokens[i]):
            i += 1
            continue

        i += 1
        has_recursive = False
        has_force = False

        while i < len(tokens):
            tok = tokens[i]
            if tok == "--":
                i += 1
                break
            if tok in RM_SEPARATORS:
                break
            if not tok.startswith("-"):
                break

            # Check for flags
            if tok == "--recursive":
                has_recursive = True
            elif tok == "--force":
                has_force = True
            elif tok.startswith("--"):
                pass  # Other long options
            else:
                # Short options like -r, -f, -rf, -ri, etc.
                if "r" in tok.lower():
                    has_recursive = True
                if "f" in tok.lower():
                    has_force = True
            i += 1

        if has_recursive and has_force:
            return True

        # Skip to next command separator or end
        while i < len(tokens) and tokens[i] not in RM_SEPARATORS:
            i += 1
        if i < len(tokens):
            i += 1  # Skip the separator

    return False


def rm_rf_targets_are_safe(command: str) -> bool:
    """Allow `rm -rf` only when *all* targets are clearly temp paths.

    IMPORTANT: We intentionally avoid trying to evaluate variables like `$TMPDIR`
    (it can be set to `/`). Only the explicit fallbacks `${TMPDIR:-/tmp}/...`
    and `${TMPDIR:-/var/tmp}/...` are allowed.
    """

    try:
        tokens = shlex.split(command, posix=True)
    except ValueError:
        return False

    i = 0
    while i < len(tokens):
        if not _is_rm_command(tokens[i]):
            i += 1
            continue

        i += 1
        flags = set()
        end_of_opts = False

        while i < len(tokens) and not end_of_opts:
            tok = tokens[i]
            if tok == "--":
                end_of_opts = True
                i += 1
                break
            if tok in RM_SEPARATORS:
                break
            if not tok.startswith("-"):
                break
            # Short options like -rf / -fr, plus long --recursive/--force variants.
            if tok.startswith("--"):
                if tok == "--recursive":
                    flags.add("r")
                elif tok == "--force":
                    flags.add("f")
            else:
                # Use .lower() to catch both -r and -R (both valid for rm)
                if "r" in tok.lower():
                    flags.add("r")
                if "f" in tok.lower():
                    flags.add("f")
            i += 1

        targets: list[str] = []
        while i < len(tokens) and tokens[i] not in RM_SEPARATORS:
            targets.append(tokens[i])
            i += 1

        if "r" in flags and "f" in flags:
            if not targets:
                return False
            for target in targets:
                if not any(target.startswith(prefix) for prefix in RM_RF_ALLOWED_PREFIXES):
                    return False

    return True


def main():
    try:
        input_data = json.load(sys.stdin)
    except json.JSONDecodeError:
        # Can't parse input, allow by default
        sys.exit(0)

    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {})
    command = tool_input.get("command", "")

    # Only check Bash commands
    if tool_name != "Bash" or not command:
        sys.exit(0)

    # Check if command matches any destructive pattern
    for pattern, reason in DESTRUCTIVE_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            if pattern.startswith("rm\\s+"):
                if rm_rf_targets_are_safe(command):
                    # rm targets are safe temp paths, allow this pattern
                    continue
                reason = (
                    "rm -rf is destructive. Only explicit temp paths are allowed "
                    f"({', '.join(RM_RF_ALLOWED_PREFIXES)})."
                )
            output = {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": (
                        f"BLOCKED by git_safety_guard.py\n\n"
                        f"Reason: {reason}\n\n"
                        f"Command: {command}\n\n"
                        f"If this operation is truly needed, ask the user for explicit "
                        f"permission and have them run the command manually."
                    )
                }
            }
            print(json.dumps(output))
            sys.exit(0)

    # Catch rm with recursive+force that bypassed the regex patterns
    # (e.g., "rm -r -f /path" or "rm --recursive --force /path")
    if has_rm_recursive_force(command) and not rm_rf_targets_are_safe(command):
        output = {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": (
                    f"BLOCKED by git_safety_guard.py\n\n"
                    f"Reason: rm -rf is destructive. Only explicit temp paths are allowed "
                    f"({', '.join(RM_RF_ALLOWED_PREFIXES)}).\n\n"
                    f"Command: {command}\n\n"
                    f"If this operation is truly needed, ask the user for explicit "
                    f"permission and have them run the command manually."
                )
            }
        }
        print(json.dumps(output))
        sys.exit(0)

    # Allow all other commands
    sys.exit(0)


if __name__ == "__main__":
    main()

#!/bin/bash
# Ultimate Bug Scanner - Claude Code Hook
# Runs on every file save for UBS-supported languages (JS/TS, Python, C/C++, Rust, Go, Java, Ruby)

if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|mjs|cjs|py|pyw|pyi|c|cc|cpp|cxx|h|hh|hpp|hxx|rs|go|java|rb)$ ]]; then
  echo "🔬 Running bug scanner..."
  if ! command -v ubs >/dev/null 2>&1; then
    echo "⚠️  'ubs' not found in PATH; install it before using this hook." >&2
    exit 0
  fi
  ubs "${PROJECT_DIR}" --ci 2>&1 | head -50
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/git_safety_guard.py"
          }
        ]
      }
    ]
  }
}

````markdown
## UBS Quick Reference for AI Agents

UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**

**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh | bash`

**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.

**Commands:**
```bash
ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
ubs $(git diff --name-only --cached)    # Staged files — before commit
ubs --only=js,python src/               # Language filter (3-5x faster)
ubs --ci --fail-on-warning .            # CI mode — before PR
ubs --help                              # Full command reference
ubs sessions --entries 1                # Tail the latest install session log
ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
```

**Output Format:**
```
⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1
```
Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail

**Fix Workflow:**
1. Read finding → category + fix suggestion
2. Navigate `file:line:col` → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run `ubs <file>` → exit 0
6. Commit

**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.

**Bug Severity:**
- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
- **Important** (production): Type narrowing, division-by-zero, resource leaks
- **Contextual** (judgment): TODO/FIXME, console logs

**Anti-Patterns:**
- ❌ Ignore findings → ✅ Investigate each
- ❌ Full scan per edit → ✅ Scope to file
- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
````

````markdown
## UBS Quick Reference for AI Agents

UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**

**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh | bash`

**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.

**Commands:**
```bash
ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
ubs $(git diff --name-only --cached)    # Staged files — before commit
ubs --only=js,python src/               # Language filter (3-5x faster)
ubs --ci --fail-on-warning .            # CI mode — before PR
ubs --help                              # Full command reference
ubs sessions --entries 1                # Tail the latest install session log
ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
```

**Output Format:**
```
⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1
```
Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail

**Fix Workflow:**
1. Read finding → category + fix suggestion
2. Navigate `file:line:col` → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run `ubs <file>` → exit 0
6. Commit

**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.

**Bug Severity:**
- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
- **Important** (production): Type narrowing, division-by-zero, resource leaks
- **Contextual** (judgment): TODO/FIXME, console logs

**Anti-Patterns:**
- ❌ Ignore findings → ✅ Investigate each
- ❌ Full scan per edit → ✅ Scope to file
- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
````

# Use bd merge for beads JSONL files
.beads/beads.jsonl merge=beads

#!/usr/bin/env bash
# Pre-commit hook to ensure pinned checksums stay up-to-date.

set -euo pipefail

compute_sha256() {
  local file="$1"
  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum "$file" | awk '{print $1}'
    return 0
  fi
  if command -v shasum >/dev/null 2>&1; then
    shasum -a 256 "$file" | awk '{print $1}'
    return 0
  fi
  if command -v openssl >/dev/null 2>&1; then
    openssl dgst -sha256 "$file" | awk '{print $NF}'
    return 0
  fi
  if command -v python3 >/dev/null 2>&1; then
    python3 - "$file" <<'PY'
import hashlib
import sys
from pathlib import Path

data = Path(sys.argv[1]).read_bytes()
print(hashlib.sha256(data).hexdigest())
PY
    return 0
  fi
  return 1
}

# Check if any pinned checksum inputs changed.
# - Pinned module sources: modules/ubs-*.sh, modules/helpers/*.{py,go,js}
# - Release checksums: install.sh, ubs
CHECKSUM_TRIGGER_CHANGED="$(
  git diff --cached --name-only | grep -E '^(install\.sh|ubs|modules/(ubs-.*\.sh|helpers/[^/]+\.(py|go|js))$)' || true
)"

if [[ -n "$CHECKSUM_TRIGGER_CHANGED" ]]; then
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "📦 Checksum inputs changed - updating checksums..."
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  
  ./scripts/update_checksums.sh
  
  if ! git diff --exit-code ubs >/dev/null 2>&1; then
    echo "✓ Updated pinned checksums in 'ubs'"
    git add ubs
  fi
  if ! git diff --exit-code SHA256SUMS >/dev/null 2>&1; then
    echo "✓ Updated release checksums in SHA256SUMS"
    git add SHA256SUMS
  fi
  echo ""
fi

# Always verify checksums match before allowing commit
echo "Verifying all checksums match..."
if ! ./scripts/verify_checksums.sh; then
  echo ""
  echo "❌ PRE-COMMIT HOOK FAILED"
  echo "Module checksums do NOT match!"
  echo ""
  echo "This should not happen if auto-update worked."
  echo "Please run: ./scripts/update_checksums.sh"
  exit 1
fi

verify_sha256sums_entry() {
  local file="$1"
  local expected actual
  expected="$(awk -v f="$file" '$2==f{print $1}' SHA256SUMS | head -n 1)"
  if [[ -z "${expected:-}" ]]; then
    echo "❌ SHA256SUMS missing entry for $file" >&2
    exit 1
  fi
  actual="$(compute_sha256 "$file")" || {
    echo "❌ Could not compute SHA256 (need sha256sum, shasum, openssl, or python3)" >&2
    exit 1
  }
  if [[ "$expected" != "$actual" ]]; then
    echo "❌ SHA256SUMS mismatch for $file" >&2
    echo "  Expected: $expected" >&2
    echo "  Actual:   $actual" >&2
    echo "  Fix: ./scripts/update_checksums.sh" >&2
    exit 1
  fi
}

verify_sha256sums_entry install.sh
verify_sha256sums_entry ubs

echo "✓ Pre-commit checks passed"

name: Notify ACFS checksum monitor

on:
  push:
    branches: [main]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
  release:
    types: [published]
  workflow_dispatch:

jobs:
  dispatch:
    runs-on: ubuntu-latest
    env:
      ACFS_TOKEN: ${{ secrets.ACFS_REPO_DISPATCH_TOKEN }}
    steps:
      - name: Skip dispatch when token missing
        if: ${{ env.ACFS_TOKEN == '' }}
        run: echo "ACFS_REPO_DISPATCH_TOKEN not set; skipping ACFS dispatch."
      - name: Dispatch to ACFS
        if: ${{ env.ACFS_TOKEN != '' }}
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ env.ACFS_TOKEN }}
          repository: Dicklesworthstone/agentic_coding_flywheel_setup
          event-type: upstream-changed
          client-payload: |
            {"repo":"${{ github.repository }}","ref":"${{ github.ref }}","sha":"${{ github.sha }}","event":"${{ github.event_name }}"}

name: Checksum Health Check

# Scheduled canary that detects stale checksums even if no pushes occur.
# Runs twice daily and creates a GitHub issue if checksums are out of sync.

on:
  schedule:
    # Run at 06:00 and 18:00 UTC every day
    - cron: '0 6,18 * * *'
  workflow_dispatch:  # Allow manual trigger

permissions:
  contents: read
  issues: write

jobs:
  health-check:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # The version-tag drift check below resolves
          # `git show v$UBS_VERSION:modules/...`. The default fetch-depth
          # of 1 doesn't include tag refs, so use 0 (full history +
          # tags) — silently missing tags would let drift slip past
          # the gate.
          fetch-depth: 0

      - name: Verify SHA256SUMS integrity
        id: verify
        run: |
          set -euo pipefail

          # Compute actual checksums
          ACTUAL_UBS=$(sha256sum ubs | awk '{print $1}')
          ACTUAL_INSTALL=$(sha256sum install.sh | awk '{print $1}')

          # Extract expected checksums (2>/dev/null suppresses error if file missing)
          EXPECTED_UBS=$(grep '  ubs$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")
          EXPECTED_INSTALL=$(grep '  install.sh$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")

          echo "ubs:"
          echo "  Expected: $EXPECTED_UBS"
          echo "  Actual:   $ACTUAL_UBS"
          echo ""
          echo "install.sh:"
          echo "  Expected: $EXPECTED_INSTALL"
          echo "  Actual:   $ACTUAL_INSTALL"

          ERRORS=""
          if [[ "$ACTUAL_UBS" != "$EXPECTED_UBS" ]]; then
            ERRORS="${ERRORS}ubs checksum mismatch\n"
          fi
          if [[ "$ACTUAL_INSTALL" != "$EXPECTED_INSTALL" ]]; then
            ERRORS="${ERRORS}install.sh checksum mismatch\n"
          fi

          # Always output the checksum values (needed for issue body even if only modules fail)
          echo "actual_ubs=$ACTUAL_UBS" >> "$GITHUB_OUTPUT"
          echo "expected_ubs=$EXPECTED_UBS" >> "$GITHUB_OUTPUT"
          echo "actual_install=$ACTUAL_INSTALL" >> "$GITHUB_OUTPUT"
          echo "expected_install=$EXPECTED_INSTALL" >> "$GITHUB_OUTPUT"

          if [[ -n "$ERRORS" ]]; then
            echo "healthy=false" >> "$GITHUB_OUTPUT"
            echo "errors<<EOF" >> "$GITHUB_OUTPUT"
            echo -e "$ERRORS" >> "$GITHUB_OUTPUT"
            echo "EOF" >> "$GITHUB_OUTPUT"
          else
            echo "healthy=true" >> "$GITHUB_OUTPUT"
            echo "::notice::All checksums are healthy"
          fi

      - name: Verify module checksums
        id: verify_modules
        run: |
          # Capture full output (with ANSI stripped) for the issue body so
          # operators can see *which* module drifted, not just that something did.
          if ./scripts/verify_checksums.sh > /tmp/modules.log 2>&1; then
            echo "modules_healthy=true" >> "$GITHUB_OUTPUT"
          else
            echo "modules_healthy=false" >> "$GITHUB_OUTPUT"
          fi
          # Strip ANSI color codes; keep only mismatch / failure lines for the body.
          sed -E 's/\x1B\[[0-9;]*[A-Za-z]//g' /tmp/modules.log \
            | grep -E '✗|MISMATCH|FAILED|Expected|Actual' \
            | head -40 > /tmp/modules_summary.log || true

      - name: Verify v$UBS_VERSION tag matches main's MODULE_CHECKSUMS (issue #45)
        id: verify_version_tag_drift
        run: |
          if ./scripts/check-version-tag-drift.sh > /tmp/tag_drift.log 2>&1; then
            echo "tag_drift_healthy=true" >> "$GITHUB_OUTPUT"
          else
            echo "tag_drift_healthy=false" >> "$GITHUB_OUTPUT"
          fi
          # Keep the operator-facing diff intact (no color codes here in
          # check-version-tag-drift.sh, but strip just in case).
          sed -E 's/\x1B\[[0-9;]*[A-Za-z]//g' /tmp/tag_drift.log \
            | head -60 > /tmp/tag_drift_summary.log || true

      - name: Check for existing issue
        id: check_issue
        if: steps.verify.outputs.healthy == 'false' || steps.verify_modules.outputs.modules_healthy == 'false' || steps.verify_version_tag_drift.outputs.tag_drift_healthy == 'false'
        run: |
          # Check if there's already an open issue with our label
          EXISTING=$(gh issue list --label "checksum-drift" --state open --json number --jq '.[0].number // empty')
          if [[ -n "$EXISTING" ]]; then
            echo "existing_issue=$EXISTING" >> "$GITHUB_OUTPUT"
            echo "::notice::Existing issue #$EXISTING found, skipping creation"
          else
            echo "existing_issue=" >> "$GITHUB_OUTPUT"
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Ensure checksum-drift label exists
        if: (steps.verify.outputs.healthy == 'false' || steps.verify_modules.outputs.modules_healthy == 'false' || steps.verify_version_tag_drift.outputs.tag_drift_healthy == 'false') && steps.check_issue.outputs.existing_issue == ''
        run: |
          # Create label if it doesn't exist (ignore error if it already exists)
          gh label create "checksum-drift" --description "Automated: SHA256SUMS out of sync" --color "B60205" 2>/dev/null || true
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Build accurate issue body
        id: build_body
        if: (steps.verify.outputs.healthy == 'false' || steps.verify_modules.outputs.modules_healthy == 'false' || steps.verify_version_tag_drift.outputs.tag_drift_healthy == 'false') && steps.check_issue.outputs.existing_issue == ''
        env:
          FILE_HEALTHY: ${{ steps.verify.outputs.healthy }}
          MODULES_HEALTHY: ${{ steps.verify_modules.outputs.modules_healthy }}
          TAG_HEALTHY: ${{ steps.verify_version_tag_drift.outputs.tag_drift_healthy }}
          EXPECTED_UBS: ${{ steps.verify.outputs.expected_ubs }}
          ACTUAL_UBS: ${{ steps.verify.outputs.actual_ubs }}
          EXPECTED_INSTALL: ${{ steps.verify.outputs.expected_install }}
          ACTUAL_INSTALL: ${{ steps.verify.outputs.actual_install }}
        run: |
          set -euo pipefail
          # Compose a category-aware issue body. Earlier versions only showed the
          # top-level file table, which masked the real failure when modules or
          # the version-tag drift check were the offenders (see #47).

          status_icon() { [[ "$1" == "true" ]] && echo "✅" || echo "❌"; }
          file_icon()   { [[ "$1" == "$2" ]] && echo "✅" || echo "❌"; }

          # Pick a title that reflects the actual failure category. If multiple
          # categories fail we fall back to a composite title.
          fail_count=0
          [[ "$FILE_HEALTHY"    == "false" ]] && fail_count=$((fail_count+1))
          [[ "$MODULES_HEALTHY" == "false" ]] && fail_count=$((fail_count+1))
          [[ "$TAG_HEALTHY"     == "false" ]] && fail_count=$((fail_count+1))
          # IMPORTANT: keep titles to plain ASCII-ish text — no literal "$",
          # no backticks, no "$(...)" command substitutions. The title is
          # consumed by the next step via the ISSUE_TITLE env var (bash expands
          # the env-var value once as a string, so a "$" inside the value is
          # safe today), but the env-var pass is the only thing protecting us.
          # If a future maintainer switches the consumer back to direct GitHub
          # Actions expression interpolation into the bash command, any "$"
          # in the title would be re-evaluated by bash as a parameter expansion
          # and silently drop unset variables. Body is fine because it is
          # read via `--body-file`, never interpolated by bash.
          if   [[ $fail_count -gt 1 ]];                       then TITLE="URGENT: Multiple checksum drift categories detected"
          elif [[ "$FILE_HEALTHY" == "false" ]];              then TITLE="URGENT: Top-level checksum drift (ubs/install.sh) — users cannot install"
          elif [[ "$MODULES_HEALTHY" == "false" ]];           then TITLE="Module checksum drift — module file does not match expected hash in ubs"
          else                                                     TITLE="Version-tag checksum drift — main modules differ from the tagged release"
          fi
          # Use the multi-line GITHUB_OUTPUT delimiter syntax so a future title
          # containing "=" or other delimiter-significant chars stays intact.
          {
            echo "title<<TITLE_EOF"
            printf '%s\n' "$TITLE"
            echo "TITLE_EOF"
          } >> "$GITHUB_OUTPUT"

          {
            echo "## Checksum Health Check Failed"
            echo ""
            echo "| Category | Status |"
            echo "|----------|--------|"
            echo "| Top-level files (\`ubs\`, \`install.sh\`)        | $(status_icon "$FILE_HEALTHY")    |"
            echo "| Module file hashes (\`MODULE_CHECKSUMS\` in ubs) | $(status_icon "$MODULES_HEALTHY") |"
            echo "| Version-tag drift (main vs the tagged release)  | $(status_icon "$TAG_HEALTHY")     |"
            echo ""

            if [[ "$FILE_HEALTHY" == "false" ]]; then
              echo "### Top-Level File Drift"
              echo ""
              echo "| File | Expected | Actual | Status |"
              echo "|------|----------|--------|--------|"
              echo "| \`ubs\`        | \`$EXPECTED_UBS\`     | \`$ACTUAL_UBS\`     | $(file_icon "$EXPECTED_UBS"     "$ACTUAL_UBS")     |"
              echo "| \`install.sh\` | \`$EXPECTED_INSTALL\` | \`$ACTUAL_INSTALL\` | $(file_icon "$EXPECTED_INSTALL" "$ACTUAL_INSTALL") |"
              echo ""
              echo "**Impact:** Users running \`install.sh\` will get checksum mismatch errors."
              echo ""
              echo "**Fix:**"
              echo ""
              echo '```bash'
              echo "./scripts/update_checksums.sh"
              echo "git add SHA256SUMS ubs"
              echo "git commit -m \"fix(checksum): sync SHA256SUMS\""
              echo "git push"
              echo '```'
              echo ""
            fi

            if [[ "$MODULES_HEALTHY" == "false" ]]; then
              echo "### Module Checksum Drift"
              echo ""
              echo "One or more module/helper files do not match the hash declared in the \`MODULE_CHECKSUMS\` table inside the \`ubs\` script. The runner will refuse to load these modules at runtime."
              echo ""
              echo "Failing entries (from \`scripts/verify_checksums.sh\`):"
              echo ""
              echo '```'
              if [[ -s /tmp/modules_summary.log ]]; then
                cat /tmp/modules_summary.log
              else
                echo "(no diagnostic lines captured — re-run scripts/verify_checksums.sh locally)"
              fi
              echo '```'
              echo ""
              echo "**Fix:** Update the module hash in \`ubs\` (search for the failing module name in the \`MODULE_CHECKSUMS\` block), or revert the module change."
              echo ""
            fi

            if [[ "$TAG_HEALTHY" == "false" ]]; then
              echo "### Version-Tag Drift (issue #45 follow-up)"
              echo ""
              echo "The current release tag's modules no longer match what main's \`ubs\` script expects (run \`scripts/check-version-tag-drift.sh\` for the exact tag name and per-module deltas). Users pinned to that tag will see runtime mismatches."
              echo ""
              echo "Drift report (from \`scripts/check-version-tag-drift.sh\`):"
              echo ""
              echo '```'
              if [[ -s /tmp/tag_drift_summary.log ]]; then
                cat /tmp/tag_drift_summary.log
              else
                echo "(no diagnostic lines captured — re-run scripts/check-version-tag-drift.sh locally)"
              fi
              echo '```'
              echo ""
              echo "**Fix one of:**"
              echo ""
              echo "1. Bump \`UBS_VERSION\` in \`ubs\` and cut a new tag whose modules match main."
              echo "2. Revert the module change(s) on main so the runner stays compatible with the existing tag."
              echo "3. Move the existing tag to the current commit (only safe if no users are pinned to it)."
              echo ""
            fi

            echo "### Why This Happened"
            echo ""
            echo "The \`Checksum Sync\` workflow auto-fixes top-level drift on push to main, but module-level and version-tag drift require human judgement (which release category they belong to). See the [Checksum Sync workflow runs](https://github.com/${{ github.repository }}/actions/workflows/checksum-sync.yml) for top-level recovery status."
            echo ""
            echo "---"
            echo "*This issue was automatically created by the Checksum Health Check workflow.*"
          } > /tmp/issue_body.md

      - name: Create issue for checksum drift
        if: (steps.verify.outputs.healthy == 'false' || steps.verify_modules.outputs.modules_healthy == 'false' || steps.verify_version_tag_drift.outputs.tag_drift_healthy == 'false') && steps.check_issue.outputs.existing_issue == ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Pass the title through an env var rather than ${{ }} interpolation
          # directly into the bash command. Direct interpolation would let bash
          # re-evaluate any "$WORD" inside the title (silently dropping unset
          # vars and, in principle, executing $(cmd) substitutions). The env-var
          # form passes the value as a string that bash expands once via "$ISSUE_TITLE".
          ISSUE_TITLE: ${{ steps.build_body.outputs.title }}
        run: |
          gh issue create \
            --title "$ISSUE_TITLE" \
            --label "checksum-drift" \
            --body-file /tmp/issue_body.md

      - name: Fail if unhealthy
        if: steps.verify.outputs.healthy == 'false' || steps.verify_modules.outputs.modules_healthy == 'false' || steps.verify_version_tag_drift.outputs.tag_drift_healthy == 'false'
        run: |
          echo "::error::Checksum drift detected! SHA256SUMS is out of sync."
          exit 1

name: Checksum Sync

on:
  push:
    branches: ["main"]
    paths:
      - "ubs"
      - "install.sh"
      - "SHA256SUMS"
  pull_request:
    paths:
      - "ubs"
      - "install.sh"
      - "SHA256SUMS"
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  group: checksum-sync-${{ github.ref_name }}
  cancel-in-progress: true

jobs:
  sync-checksums:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # Need write access for auto-commit on push to main
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 1

      - name: Compute current checksums
        id: compute
        run: |
          # Compute actual checksums for both files
          ACTUAL_UBS=$(sha256sum ubs | awk '{print $1}')
          ACTUAL_INSTALL=$(sha256sum install.sh | awk '{print $1}')

          # Extract expected checksums (grep for specific file to avoid multi-line issues)
          EXPECTED_UBS=$(grep '  ubs$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")
          EXPECTED_INSTALL=$(grep '  install.sh$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")

          echo "actual_ubs=$ACTUAL_UBS" >> "$GITHUB_OUTPUT"
          echo "actual_install=$ACTUAL_INSTALL" >> "$GITHUB_OUTPUT"
          echo "expected_ubs=$EXPECTED_UBS" >> "$GITHUB_OUTPUT"
          echo "expected_install=$EXPECTED_INSTALL" >> "$GITHUB_OUTPUT"

          # Check if both match
          if [[ "$ACTUAL_UBS" == "$EXPECTED_UBS" && "$ACTUAL_INSTALL" == "$EXPECTED_INSTALL" ]]; then
            echo "match=true" >> "$GITHUB_OUTPUT"
            echo "::notice::SHA256SUMS is up to date"
          else
            echo "match=false" >> "$GITHUB_OUTPUT"
            if [[ "$ACTUAL_UBS" != "$EXPECTED_UBS" ]]; then
              echo "::warning::ubs checksum mismatch (expected $EXPECTED_UBS, actual $ACTUAL_UBS)"
            fi
            if [[ "$ACTUAL_INSTALL" != "$EXPECTED_INSTALL" ]]; then
              echo "::warning::install.sh checksum mismatch (expected $EXPECTED_INSTALL, actual $ACTUAL_INSTALL)"
            fi
          fi

      - name: Verify checksums (PR only)
        if: github.event_name == 'pull_request' && steps.compute.outputs.match == 'false'
        run: |
          echo "::error::SHA256SUMS does not match current files!"
          echo ""
          echo "ubs checksum:"
          echo "  Expected: ${{ steps.compute.outputs.expected_ubs }}"
          echo "  Actual:   ${{ steps.compute.outputs.actual_ubs }}"
          echo ""
          echo "install.sh checksum:"
          echo "  Expected: ${{ steps.compute.outputs.expected_install }}"
          echo "  Actual:   ${{ steps.compute.outputs.actual_install }}"
          echo ""
          echo "Please run: ./scripts/update_checksums.sh"
          exit 1

      - name: Auto-update SHA256SUMS (push to main only)
        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.compute.outputs.match == 'false'
        run: |
          # Create SHA256SUMS with both entries (install.sh first, then ubs)
          echo "${{ steps.compute.outputs.actual_install }}  install.sh" > SHA256SUMS
          echo "${{ steps.compute.outputs.actual_ubs }}  ubs" >> SHA256SUMS
          echo "Updated SHA256SUMS:"
          cat SHA256SUMS

      - name: Commit and push updated checksums
        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.compute.outputs.match == 'false'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add SHA256SUMS
          git commit -m "chore(checksum): auto-update SHA256SUMS [skip ci]

          Updated checksums:
            install.sh: ${{ steps.compute.outputs.actual_install }}
            ubs: ${{ steps.compute.outputs.actual_ubs }}

          This commit was automatically generated by the checksum-sync workflow."
          git push

name: CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref_name }}
  cancel-in-progress: true

env:
  UBS_NO_AUTO_UPDATE: "1"

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # The version-tag drift check below resolves
          # `git show v$UBS_VERSION:modules/...`. The default fetch-depth
          # of 1 doesn't include tag refs, so use 0 (full history +
          # tags) — the repo is small enough that the cost is
          # negligible and silently missing tags would let drift slip
          # past the check.
          fetch-depth: 0

      - name: Syntax-check shell scripts
        run: |
          bash -n install.sh
          bash -n ubs

      - name: Verify entrypoint loads
        run: ./ubs --help >/dev/null

      - name: Verify v$UBS_VERSION tag matches MODULE_CHECKSUMS (issue #45)
        # Catches the recurring distribution-drift bug: install.sh
        # ships the latest `main` runner, but `ubs` fetches modules
        # from v${UBS_VERSION}. If main's MODULE_CHECKSUMS table
        # advances past the tag without bumping UBS_VERSION, every
        # fresh install hits checksum mismatch on `ubs doctor --fix`.
        # See https://github.com/Dicklesworthstone/ultimate_bug_scanner/issues/45
        run: ./scripts/check-version-tag-drift.sh

  test:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up uv with caching
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"
          enable-cache: true
          cache-dependency-glob: |
            uv.lock

      - name: Install system tools
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends jq ripgrep

      - name: Install ast-grep
        run: npm install -g @ast-grep/cli >/dev/null

      - name: Sync Python dependencies
        run: uv sync --locked --python 3.13

      - name: Run manifest smoke suite
        env:
          NO_COLOR: "1"
          UBS_LOG_JSON: "1"
        run: |
          cd test-suite && uv run python run_manifest.py --fail-fast \
            --case js-core-buggy \
            --case js-core-clean \
            --case js-node-buggy \
            --case js-node-clean \
            --case golang-buggy \
            --case golang-clean \
            --case cpp-buggy \
            --case cpp-clean \
            --case rust-buggy \
            --case rust-clean \
            --case java-buggy \
            --case java-clean \
            --case ruby-buggy \
            --case ruby-clean

      - name: Run helper test suites
        env:
          NO_COLOR: "1"
          UBS_LOG_JSON: "1"
        run: |
          uv run python test-suite/shareable/test_shareable_reports.py
          uv run python test-suite/python/tests/test_resource_helper.py
          uv run python test-suite/python/tests/test_git_safety_guard.py
          uv run python test-suite/java/tests/test_resource_lifecycle_helper.py
          uv run python test-suite/csharp/tests/test_helper_scanners.py

  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install shellcheck
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends shellcheck

      - name: Run shellcheck
        run: |
          shellcheck -S error install.sh ubs modules/*.sh scripts/*.sh

      - name: Compile-check Python files
        run: python3 -m compileall scripts modules/helpers

name: UBS Manifest

on:
  push:
    branches: ["main"]
  pull_request:
  workflow_dispatch:

jobs:
  manifest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up uv with caching
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"
          enable-cache: true
          cache-dependency-glob: |
            uv.lock
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y python3 jq ripgrep >/dev/null
      - name: Install ast-grep (npm)
        run: npm install -g @ast-grep/cli >/dev/null
      - name: Run UBS manifest suite
        env:
          NO_COLOR: "1"
          UBS_NO_AUTO_UPDATE: "1"
          UBS_LOG_JSON: "1"
        run: |
          cd test-suite
          uv run python run_manifest.py --fail-fast

name: Nix Flake

on:
  push:
    branches: ["main"]
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  flake-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Nix
        uses: cachix/install-nix-action@v27
        with:
          install_url: https://releases.nixos.org/nix/nix-2.18.1/install
          extra_nix_config: |
            experimental-features = nix-command flakes

      - name: Run nix flake check
        run: nix flake check

# installer-notify.yml
# Copy this to .github/workflows/ in your project
# Notifies ACFS when install.sh changes
#
# Setup:
# 1. Create a GitHub PAT with `repo` scope
# 2. Add it as ACFS_DISPATCH_TOKEN secret in your repo
# 3. Copy this file to .github/workflows/

name: Notify ACFS of Installer Change

on:
  push:
    branches: [main]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
      - '**/install.sh'
  pull_request:
    branches: [main]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
      - '**/install.sh'

concurrency:
  group: installer-notify-${{ github.ref }}
  cancel-in-progress: true

jobs:
  notify-acfs:
    # Only notify on push to main, not PRs
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Compute installer SHA256
        id: checksum
        run: |
          # Find the installer file
          if [ -f install.sh ]; then
            INSTALLER_PATH="install.sh"
          elif [ -f scripts/install.sh ]; then
            INSTALLER_PATH="scripts/install.sh"
          else
            echo "No installer found"
            exit 1
          fi

          SHA256=$(sha256sum "$INSTALLER_PATH" | cut -d' ' -f1)
          echo "sha256=$SHA256" >> $GITHUB_OUTPUT
          echo "Computed SHA256: $SHA256"

      - name: Notify ACFS
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.ACFS_DISPATCH_TOKEN }}
          repository: Dicklesworthstone/agentic_coding_flywheel_setup
          event-type: installer-updated
          client-payload: |
            {
              "tool": "${{ github.event.repository.name }}",
              "repo": "${{ github.repository }}",
              "commit": "${{ github.sha }}",
              "new_sha256": "${{ steps.checksum.outputs.sha256 }}",
              "ref": "${{ github.ref }}",
              "actor": "${{ github.actor }}"
            }

      - name: Log notification
        run: |
          echo "::notice::Notified ACFS about installer change"
          echo "Repository: ${{ github.repository }}"
          echo "Commit: ${{ github.sha }}"
          echo "SHA256: ${{ steps.checksum.outputs.sha256 }}"

  # Validate installer syntax on PRs
  validate-installer:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shellcheck
        run: sudo apt-get update && sudo apt-get install -y shellcheck

      - name: Shellcheck installer
        run: |
          EXIT_CODE=0
          for script in install.sh scripts/install.sh; do
            if [ -f "$script" ]; then
              echo "Checking $script..."
              shellcheck "$script" || EXIT_CODE=1
            fi
          done
          exit $EXIT_CODE

name: OCI Image

on:
  push:
    branches: ["main"]
    tags:
      - "v*"
  workflow_dispatch:

permissions:
  contents: read
  packages: write
  id-token: write

jobs:
  build-sign-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Normalize image name
        run: echo "IMAGE_NAME=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/ubs-tools" >> "$GITHUB_ENV"

      - name: Compute image tags
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            {
              echo "IMAGE_TAGS<<EOF"
              echo "${IMAGE_NAME}:${GITHUB_SHA}"
              echo "EOF"
            } >> "$GITHUB_ENV"
          else
            {
              echo "IMAGE_TAGS<<EOF"
              echo "${IMAGE_NAME}:${GITHUB_SHA}"
              echo "${IMAGE_NAME}:latest"
              # Add version tag if this is a tag push (e.g., v5.0.2)
              if [[ "${{ github.ref_type }}" == "tag" ]]; then
                echo "${IMAGE_NAME}:${{ github.ref_name }}"
              fi
              echo "EOF"
            } >> "$GITHUB_ENV"
          fi

      - name: Set up QEMU (for multi-platform builds)
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push image
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: ${{ github.event_name != 'pull_request' }}
          load: false
          tags: ${{ env.IMAGE_TAGS }}
          provenance: false
          sbom: false

      - name: Capture image digest
        id: digest
        if: github.event_name != 'pull_request'
        run: |
          DIGEST="${{ steps.build.outputs.digest }}"
          if [ -z "$DIGEST" ]; then
            echo "Image digest missing from docker/build-push-action output" >&2
            exit 1
          fi
          DIGEST_HASH="${DIGEST#sha256:}"
          IMAGE_DIGEST="${IMAGE_NAME}@sha256:${DIGEST_HASH}"
          echo "digest=$IMAGE_DIGEST" >> "$GITHUB_OUTPUT"
          echo "sha=$DIGEST_HASH" >> "$GITHUB_OUTPUT"

      - name: Install syft
        if: github.event_name != 'pull_request'
        uses: anchore/sbom-action/download-syft@v0
        with:
          syft-version: v1.4.1

      - name: Generate SBOM (SPDX JSON)
        if: github.event_name != 'pull_request'
        run: |
          IMAGE_REF="${{ steps.digest.outputs.digest }}"
          syft "$IMAGE_REF" -o spdx-json > sbom.spdx.json

      - name: Install cosign
        if: github.event_name != 'pull_request'
        uses: sigstore/cosign-installer@v3.6.0
        with:
          cosign-release: v2.2.4

      - name: Sign image (keyless)
        env:
          COSIGN_EXPERIMENTAL: "1"
        if: github.event_name != 'pull_request'
        run: cosign sign --yes ${{ steps.digest.outputs.digest }}

      - name: Attach SBOM attestation
        env:
          COSIGN_EXPERIMENTAL: "1"
        if: github.event_name != 'pull_request'
        run: cosign attest --yes --predicate sbom.spdx.json --type spdx ${{ steps.digest.outputs.digest }}

      - name: Generate provenance predicate (SLSA v1)
        if: github.event_name != 'pull_request'
        run: |
          cat > provenance.json <<'EOF'
          {
            "_type": "https://in-toto.io/Statement/v1",
            "subject": [
              { "name": "${{ env.IMAGE_NAME }}", "digest": { "sha256": "${{ steps.digest.outputs.sha }}" } }
            ],
            "predicateType": "https://slsa.dev/provenance/v1",
            "predicate": {
              "buildDefinition": {
                "buildType": "https://slsa.dev/provenance/v1",
                "externalParameters": {
                  "source": "${{ github.repository }}",
                  "ref": "${{ github.ref }}",
                  "sha": "${{ github.sha }}"
                }
              },
              "runDetails": {
                "builder": { "id": "https://github.com/actions" },
                "metadata": { "invocationId": "${{ github.run_id }}" }
              }
            }
          }
          EOF

      - name: Attach provenance attestation (SLSA v1)
        env:
          COSIGN_EXPERIMENTAL: "1"
        if: github.event_name != 'pull_request'
        run: cosign attest --yes --predicate provenance.json --type https://slsa.dev/provenance/v1 ${{ steps.digest.outputs.digest }}

      - name: Upload SBOM artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: sbom-spdx
          path: sbom.spdx.json

      - name: Upload provenance artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: oci-provenance
          path: provenance.json

name: Legacy Release Artifacts (disabled)

# Retained to honor the no-delete policy. The actual release process now lives in
# .github/workflows/release.yml. This workflow is gated off by default to avoid
# duplicate releases; run manually if you need the older path.

on:
  workflow_dispatch:

jobs:
  noop:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Legacy release workflow replaced by release.yml"

name: Release

on:
  push:
    tags:
      - "v*"
  workflow_dispatch:

permissions:
  contents: write
  packages: write
  id-token: write

env:
  COSIGN_VERSION: v2.2.4
  SYFT_VERSION: v1.4.1
  UV_VERSION: "0.4.20"
  JQ_VERSION: "1.7.1"
  RG_VERSION: "13.0.0"

jobs:
  gather:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}
      tag: ${{ steps.meta.outputs.tag }}
    steps:
      - name: Compute release metadata
        id: meta
        run: |
          TAG="${GITHUB_REF_NAME}"
          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"

  nix-check:
    runs-on: ubuntu-latest
    needs: gather
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Nix
        uses: cachix/install-nix-action@v27
        with:
          install_url: https://releases.nixos.org/nix/nix-2.18.1/install
          extra_nix_config: |
            experimental-features = nix-command flakes

      - name: Run nix flake check
        run: nix flake check

  build-artifacts:
    runs-on: ubuntu-latest
    needs: gather
    env:
      TAG: ${{ needs.gather.outputs.tag }}
      VERSION: ${{ needs.gather.outputs.version }}
    steps:
      - name: Ensure minisign secret is present
        run: |
          if [ -z "${{ secrets.MINISIGN_SECRET_KEY }}" ]; then
            echo "MINISIGN_SECRET_KEY is required for releases" >&2
            exit 1
          fi

      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install pinned tooling
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends ca-certificates curl dpkg-dev coreutils minisign

          # jq (static binary)
          curl -fsSLo /usr/local/bin/jq "https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64"
          echo "5942c9b0934e510ee61eb3e30273f1b3fe2590df93933a93d7c58b81d19c8ff5  /usr/local/bin/jq" | sha256sum --check --status
          chmod +x /usr/local/bin/jq

          # ripgrep (13.0.0 deb)
          curl -fsSLo "/tmp/ripgrep_${RG_VERSION}_amd64.deb" "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/ripgrep_${RG_VERSION}_amd64.deb"
          echo "6d78bed13722019cb4f9d0cf366715e2dcd589f4cf91897efb28216a6bb319f1  /tmp/ripgrep_${RG_VERSION}_amd64.deb" | sha256sum --check --status
          sudo dpkg -i "/tmp/ripgrep_${RG_VERSION}_amd64.deb"

      - name: Set up uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"
          enable-cache: false
          version: ${{ env.UV_VERSION }}

      - name: Verify tag matches VERSION file
        run: |
          FILE_VERSION=$(tr -d '\r\n' < VERSION)
          if [ "$FILE_VERSION" != "$VERSION" ]; then
            echo "VERSION file ($FILE_VERSION) does not match tag ($VERSION)" >&2
            exit 1
          fi

      - name: Create dist directory
        run: mkdir -p dist

      - name: Generate checksums
        run: |
          sha256sum install.sh ubs scripts/verify.sh > dist/SHA256SUMS

      - name: Sign checksums with minisign
        env:
          MINISIGN_SECRET_KEY: ${{ secrets.MINISIGN_SECRET_KEY }}
        run: |
          printf "%s" "$MINISIGN_SECRET_KEY" > dist/minisign.key
          chmod 600 dist/minisign.key
          minisign -S -s dist/minisign.key -m dist/SHA256SUMS -x dist/SHA256SUMS.minisig
          rm dist/minisign.key

      - name: Install syft
        uses: anchore/sbom-action/download-syft@v0
        with:
          syft-version: ${{ env.SYFT_VERSION }}

      - name: Generate project SBOM (SPDX JSON)
        run: syft dir:. -o spdx-json > dist/sbom.spdx.json

      - name: Build Homebrew formula
        run: |
          UBS_SHA=$(sha256sum ubs | cut -d' ' -f1)
          cat > dist/ubs.rb <<'RUBY'
          class Ubs < Formula
            desc "Ultimate Bug Scanner meta-runner"
            homepage "https://github.com/Dicklesworthstone/ultimate_bug_scanner"
          RUBY
          {
            echo "  version \"$VERSION\""
            echo "  url \"https://github.com/Dicklesworthstone/ultimate_bug_scanner/releases/download/v$VERSION/ubs\""
            echo "  sha256 \"$UBS_SHA\""
          } >> dist/ubs.rb
          cat >> dist/ubs.rb <<'RUBY'
          license "MIT"

          def install
            chmod 0555, "ubs"
            bin.install "ubs"
          end

          test do
            system "#{bin}/ubs", "--help"
          end
          end
          RUBY
          perl -pi -e 's/^ {10}//' dist/ubs.rb

      - name: Assemble release payload
        run: |
          cp install.sh dist/
          cp ubs dist/
          cp scripts/verify.sh dist/

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: release-artifacts
          path: dist

  oci-image:
    runs-on: ubuntu-latest
    needs: gather
    env:
      TAG: ${{ needs.gather.outputs.tag }}
      VERSION: ${{ needs.gather.outputs.version }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Normalize image name
        run: echo "IMAGE_NAME=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/ubs-tools" >> "$GITHUB_ENV"

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push image
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ env.IMAGE_NAME }}:${{ github.sha }}
            ${{ env.IMAGE_NAME }}:${{ env.TAG }}
            ${{ env.IMAGE_NAME }}:latest
          provenance: false
          sbom: false

      - name: Capture image digest
        id: digest
        run: |
          DIGEST="${{ steps.build.outputs.digest }}"
          if [ -z "$DIGEST" ]; then
            echo "Image digest missing from docker/build-push-action output" >&2
            exit 1
          fi
          DIGEST_HASH="${DIGEST#sha256:}"
          IMAGE_DIGEST="${IMAGE_NAME}@sha256:${DIGEST_HASH}"
          echo "digest=$IMAGE_DIGEST" >> "$GITHUB_OUTPUT"
          echo "sha=$DIGEST_HASH" >> "$GITHUB_OUTPUT"

      - name: Install syft
        uses: anchore/sbom-action/download-syft@v0
        with:
          syft-version: ${{ env.SYFT_VERSION }}

      - name: Generate SBOM (SPDX JSON)
        run: syft ${{ steps.digest.outputs.digest }} -o spdx-json > sbom.spdx.json

      - name: Install cosign
        uses: sigstore/cosign-installer@v3.6.0
        with:
          cosign-release: ${{ env.COSIGN_VERSION }}

      - name: Sign image (keyless)
        env:
          COSIGN_EXPERIMENTAL: "1"
        run: cosign sign --yes ${{ steps.digest.outputs.digest }}

      - name: Attach SBOM attestation
        env:
          COSIGN_EXPERIMENTAL: "1"
        run: cosign attest --yes --predicate sbom.spdx.json --type spdx ${{ steps.digest.outputs.digest }}

      - name: Generate provenance predicate (SLSA v1)
        run: |
          cat > provenance.json <<'EOF'
          {
            "_type": "https://in-toto.io/Statement/v1",
            "subject": [
              { "name": "${{ env.IMAGE_NAME }}", "digest": { "sha256": "${{ steps.digest.outputs.sha }}" } }
            ],
            "predicateType": "https://slsa.dev/provenance/v1",
            "predicate": {
              "buildDefinition": {
                "buildType": "https://slsa.dev/provenance/v1",
                "externalParameters": {
                  "source": "${{ github.repository }}",
                  "ref": "${{ github.ref }}",
                  "sha": "${{ github.sha }}"
                }
              },
              "runDetails": {
                "builder": { "id": "https://github.com/actions" },
                "metadata": { "invocationId": "${{ github.run_id }}" }
              }
            }
          }
          EOF
          perl -pi -e 's/^ {10}//' provenance.json

      - name: Attach provenance attestation (SLSA v1)
        env:
          COSIGN_EXPERIMENTAL: "1"
        run: cosign attest --yes --predicate provenance.json --type https://slsa.dev/provenance/v1 ${{ steps.digest.outputs.digest }}

      - name: Upload OCI artifacts
        uses: actions/upload-artifact@v4
        with:
          name: oci-artifacts
          path: |
            sbom.spdx.json
            provenance.json

  publish:
    runs-on: ubuntu-latest
    needs:
      - build-artifacts
      - oci-image
      - nix-check
    steps:
      - name: Download release artifacts
        uses: actions/download-artifact@v4
        with:
          name: release-artifacts
          path: dist

      - name: Download OCI artifacts
        uses: actions/download-artifact@v4
        with:
          name: oci-artifacts
          path: oci

      - name: Normalize OCI artifact names
        run: |
          mv oci/sbom.spdx.json oci/oci-sbom.spdx.json
          mv oci/provenance.json oci/oci-provenance.json

      - name: Extract version from tag
        id: version
        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT

      - name: Create GitHub release
        uses: softprops/action-gh-release@v2
        with:
          files: |
            dist/install.sh
            dist/ubs
            dist/SHA256SUMS
            dist/SHA256SUMS.minisig
            dist/ubs.rb
            dist/sbom.spdx.json
            oci/oci-sbom.spdx.json
            oci/oci-provenance.json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    outputs:
      version: ${{ steps.version.outputs.version }}

  # ==========================================================================
  # Notify Package Managers to Update
  # ==========================================================================
  notify-homebrew-tap:
    name: Notify Homebrew Tap
    runs-on: ubuntu-latest
    needs: publish
    env:
      TAP_TOKEN: ${{ secrets.ACFS_REPO_DISPATCH_TOKEN }}
    steps:
      - name: Skip dispatch when token missing
        if: ${{ env.TAP_TOKEN == '' }}
        run: |
          echo "::warning::ACFS_REPO_DISPATCH_TOKEN not set; skipping Homebrew tap dispatch."
          echo "The tap's scheduled check (every 6h) will pick up the new version automatically."

      - name: Trigger formula update
        if: ${{ env.TAP_TOKEN != '' }}
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ env.TAP_TOKEN }}
          repository: Dicklesworthstone/homebrew-tap
          event-type: formula-update
          client-payload: |
            {
              "tool": "ubs",
              "version": "${{ needs.publish.outputs.version }}"
            }

      - name: Log dispatch
        if: ${{ env.TAP_TOKEN != '' }}
        run: |
          echo "✅ Dispatched formula-update event to homebrew-tap"
          echo "   Tool: ubs"
          echo "   Version: ${{ needs.publish.outputs.version }}"

name: UBS Test Suite

on:
  push:
    branches: ["main"]
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  actions: write

concurrency:
  group: test-suite-${{ github.workflow }}-${{ github.ref_name }}
  cancel-in-progress: true

jobs:
  tests:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    defaults:
      run:
        shell: bash
    env:
      UBS_NO_AUTO_UPDATE: "1"
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Verify checksums (early fail if stale)
        run: |
          echo "Verifying SHA256SUMS integrity..."
          ACTUAL_UBS=$(sha256sum ubs | awk '{print $1}')
          ACTUAL_INSTALL=$(sha256sum install.sh | awk '{print $1}')
          EXPECTED_UBS=$(grep '  ubs$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")
          EXPECTED_INSTALL=$(grep '  install.sh$' SHA256SUMS 2>/dev/null | awk '{print $1}' || echo "")

          FAIL=0
          if [[ "$ACTUAL_UBS" != "$EXPECTED_UBS" ]]; then
            echo "::error::ubs checksum mismatch (expected $EXPECTED_UBS, got $ACTUAL_UBS)"
            FAIL=1
          fi
          if [[ "$ACTUAL_INSTALL" != "$EXPECTED_INSTALL" ]]; then
            echo "::error::install.sh checksum mismatch (expected $EXPECTED_INSTALL, got $ACTUAL_INSTALL)"
            FAIL=1
          fi

          if [[ "$FAIL" -eq 1 ]]; then
            echo ""
            echo "SHA256SUMS is out of sync! Run: ./scripts/update_checksums.sh"
            exit 1
          fi
          echo "All checksums verified!"

      - name: Set up uv with caching
        uses: astral-sh/setup-uv@v7
        with:
          python-version: "3.13"
          enable-cache: true
          cache-dependency-glob: |
            uv.lock

      - name: Install system tools
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends jq ripgrep
      - name: Install ast-grep (npm)
        run: npm install -g @ast-grep/cli >/dev/null

      - name: Sync Python dependencies
        run: uv sync --locked --python 3.13

      - name: Run full test suite
        env:
          NO_COLOR: "1"
          UBS_NO_AUTO_UPDATE: "1"
          UBS_LOG_JSON: "1"
        run: ./test-suite/run_all.sh

# Test files
test/
*.test.js
*.test.txt

# Backup files
*.backup
*.bak

# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/
.idea/
*.swp
*.swo
*~

# Temporary files
tmp/
temp/
*.tmp
.bv/

# Beads ephemeral files
.beads/last-touched
.beads/.bv.lock
.beads/.local_version
.beads/daemon.lock
.beads/daemon.log
.beads/daemon-*.log
.beads/daemon-*.log.gz
.beads/*.db
.beads/*.db-*
.beads/*.sqlite
.beads/*.sqlite-*
.beads/*.sqlite3
.beads/*.sqlite3-*
.beads/*.migrated

# Python environments
.venv/
__pycache__/
*.pyc
*.pyo

# Rust build artifacts
**/target/
**/*.rs.bk
Cargo.lock

# Test artifacts
test-suite/artifacts/
rule-quality-variants/

# Compiled test artifacts
a.out

# Bead dump exports (dated ephemeral reports)
*_bead_dump_*.txt

# Beads history snapshots
.beads/.br_history/

# Profiling data
perf.data
perf.data.*

# Local scratch DBs
storage.sqlite3
storage.sqlite3-*
*.sqlite3.bak

# Prompt dump files (agent-generated diagnostic exports)
prompt_dump*.md
modules/prompt_dump*.md

# Agent-generated planning/reasoning scratch artifacts
modes-of-reasoning-*.md
reasoning-mode-*.md
*_modes_of_reasoning*.md
MOR_*.md
artifact-*.json
artifacts/*.json

# Tool caches
.ruff_cache/

# macOS resource fork files
._*

# bv graph output
--graph-format.svg

# ACFS ephemeral patterns (auto-generated agent artifacts)
core
core.*
cline.mcp.json
codex.mcp.json
cursor.mcp.json
gemini.mcp.json
opencode.json
windsurf.mcp.json
*.mcp.json.*.bak
.opencode.json.*.bak
.windsurf.mcp.json.*.bak
.agent-mail-project-id
.agent-mail.yaml
*.sqlite3.corrupt*
storage.sqlite3.corrupt-*
storage.sqlite3-shm.corrupt-*
storage.sqlite3-wal.corrupt-*
.beads/*.corrupt*
.beads/*.pre_repair_*
.beads/*.repair_candidate_*
.beads/*.bak-corrupt
tmp-rel-*

````markdown
## UBS Quick Reference for AI Agents

UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**

**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh | bash`

**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.

**Commands:**
```bash
ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
ubs $(git diff --name-only --cached)    # Staged files — before commit
ubs --only=js,python src/               # Language filter (3-5x faster)
ubs --ci --fail-on-warning .            # CI mode — before PR
ubs --help                              # Full command reference
ubs sessions --entries 1                # Tail the latest install session log
ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
```

**Output Format:**
```
⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1
```
Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail

**Fix Workflow:**
1. Read finding → category + fix suggestion
2. Navigate `file:line:col` → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run `ubs <file>` → exit 0
6. Commit

**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.

**Bug Severity:**
- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
- **Important** (production): Type narrowing, division-by-zero, resource leaks
- **Contextual** (judgment): TODO/FIXME, console logs

**Anti-Patterns:**
- ❌ Ignore findings → ✅ Investigate each
- ❌ Full scan per edit → ✅ Scope to file
- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
````

## Ultimate Bug Scanner ignore list
# Paths/globs listed here are skipped by `./ubs` (similar to .gitignore semantics).
# Useful for excluding intentionally buggy fixtures, generated assets, or vendor dirs.

test-suite/
rule-quality-variants/
modules/helpers/*.go
modules/helpers/resource_lifecycle_go.go
modules/helpers/type_narrowing_ts.js

FROM debian:bookworm-slim

ENV UBS_NO_AUTO_UPDATE=1 \
    DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      bash ca-certificates curl jq ripgrep \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY ubs install.sh README.md /app/

RUN chmod +x /app/ubs /app/install.sh

ENTRYPOINT ["/app/ubs"]
CMD ["--help"]

LABEL org.opencontainers.image.title="Ultimate Bug Scanner" \
      org.opencontainers.image.description="Meta-runner for multi-language bug scanning" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.source="https://github.com/Dicklesworthstone/ultimate_bug_scanner"

5.3.2