chore: update submodule refs, clean up plans/evidence, update .gitignore

.omo/plans/archived/optimize-update-sh.md

@@ -0,0 +1,252 @@
+# Optimize update.sh — Conditional Rebuild Only When Needed
+
+## TL;DR
+
+> **Quick Summary**: Modify `update.sh` to skip Docker rebuild, restart, and migration when no git/submodule/`.env` changes are detected. Prevents unnecessary 2-5 minute downtime on every run.
+>
+> **Deliverables**:
+> - `update.sh` — refactored with conditional rebuild logic
+> - `.update-state` — persistent state file (gitignored)
+> - `.gitignore` — add `.update-state` entry
+>
+> **Estimated Effort**: Quick
+> **Parallel Execution**: N/A (single file)
+> **Critical Path**: N/A
+
+---
+
+## Context
+
+### Original Request
+User noticed `./update.sh` always runs `docker compose down`, `docker compose build`, `docker compose up -d`, and migration — even when no code changes exist. This wastes time (2-5 min) and causes unnecessary downtime.
+
+### Metis Review — Key Findings
+
+**Critical Gap #1**: `.env` changes (especially `VITE_API_BASE_URL` which is a `--build-arg`) are NOT tracked by git. Must hash `.env` content alongside git state.
+
+**Critical Gap #2**: State file location must be `.gitignore`'d. Use `./.update-state` with atomic write (tmp + mv).
+
+**Critical Gap #3**: No force-rebuild mechanism. Must add `--force` flag.
+
+**Minor Gap #4**: `md5sum` not portable to macOS. Use `openssl sha256`.
+
+**Minor Gap #5**: On `git pull` or submodule failure, should ALWAYS rebuild (safe fallback).
+
+---
+
+## Work Objectives
+
+### Core Objective
+Skip Docker rebuild/restart/migration cycle when git state, submodule state, and `.env` are unchanged from last successful update.
+
+### Concrete Deliverables
+- `update.sh` — refactored with state comparison + conditional rebuild
+- `.update-state` — persistent state file (auto-created, never committed)
+- `.gitignore` — add `.update-state` entry
+
+### Definition of Done
+- [x] Second consecutive run with no changes prints "No changes detected. Skipping." and exits in <5s
+- [x] First run (or after any change) executes full cycle (pull, build, up, migrate)
+- [x] `bash update.sh --force` always executes full cycle
+- [x] `.env` change (esp. `VITE_API_BASE_URL`) triggers rebuild even without git change
+- [x] Git pull failure triggers rebuild (safe fallback)
+- [x] Corrupted state file treated as first run → always builds
+
+### Must Have
+- Conditional rebuild: only when git HEAD, submodules, or `.env` changed
+- `--force` flag to bypass state check
+- `.update-state` properly gitignored
+- Clean output: clear `[+]` / `[-]` indicators for skip vs rebuild paths
+
+### Must NOT Have (Guardrails)
+- Do NOT change the `down → build → up` cycle pattern when rebuild IS needed
+- Do NOT add per-submodule selective build (always build all or nothing)
+- Do NOT add Docker health-check polling or auto-rollback
+- Do NOT modify any file other than `update.sh` and `.gitignore`
+- Do NOT use `docker-compose` (v1) anywhere
+
+---
+
+## Verification Strategy
+
+> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed.
+
+### Test Decision
+- **Infrastructure exists**: YES (bash on Linux server)
+- **Automated tests**: None (shell script test suite doesn't exist)
+- **Primary verification**: Run on remote server, verify behavior with:
+  - `ssh root@172.20.8.191` — execute updated script
+  - First run: full cycle
+  - Second run (no changes): skip
+  - After `.env` edit: rebuild
+  - With `--force`: rebuild
+
+---
+
+## Execution Strategy
+
+Single task, no waves needed — one file change.
+
+---
+
+## TODOs
+
+_All tasks completed in commit `0b943ae`_
+
+- [x] 1. Refactor `update.sh` — Add State Comparison & Conditional Rebuild Logic
+
+  **What to do**:
+  - Add at top of script (after `set -e`): define `STATE_FILE=".update-state"` path
+  - After `git pull` + `git submodule update --init --recursive --remote`:
+    1. Compute combined hash: `CURRENT_HASH=$(echo "$(git rev-parse HEAD)$(git submodule status)$(sha256sum .env)" | sha256sum | cut -d' ' -f1)`
+    2. Read previous hash from `$STATE_FILE` (if exists)
+    3. If `$CURRENT_HASH` matches previous AND `--force` not passed → skip rebuild
+    4. Otherwise → execute full `down → build → up -d → migrate → backfill` cycle
+  - Write new hash atomically: `echo "$CURRENT_HASH" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"`
+  - Handle `--force` flag: `if [ "$1" = "--force" ]; then ...`
+  - Handle missing/corrupt state file (treat as first run → build)
+  - Handle `git pull` failure (always build as safe fallback)
+  - Handle `git submodule update` failure (always build as safe fallback)
+  - Print clear `[+]`/`[-]` output for skip vs rebuild paths
+
+  **Must NOT do**:
+  - Do NOT change the `down → build → up` cycle pattern (preserve existing)
+  - Do NOT add per-service selective build
+  - Do NOT modify any existing command flags or environment sourcing
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Single file, well-defined logic, no external dependencies
+  - **Skills**: `[]`
+
+  **Parallelization**:
+  - **Can Run In Parallel**: N/A (single task)
+
+  **References**:
+  - `update.sh` — Current file to refactor (52 lines)
+  - `.gitignore:41` — `connect_remote.txt` already listed; add `.update-state` nearby
+
+  **Acceptance Criteria**:
+  - [x] Script runs full cycle on first invocation (no `.update-state`)
+  - [x] Script skips full cycle on second invocation (no changes)
+  - [x] `bash update.sh --force` always runs full cycle
+  - [x] `.env` change triggers rebuild (hash detects difference)
+  - [x] Corrupted `.update-state` treated as first run
+  - [x] `git pull` failure → rebuild triggered (safe fallback)
+  - [x] All output clear and actionable
+
+  **QA Scenarios**:
+
+  ```
+  Scenario A: Second run skips rebuild (no changes) ✅
+    Tool: Bash (interactive_bash via tmux on server)
+    Preconditions: State file created with correct hash
+    Steps:
+      1. ssh root@172.20.8.191
+      2. cd /root/Nexus-Guard-Suite
+      3. hash=$(echo "$(git rev-parse HEAD)$(git submodule status)$(sha256sum .env)" | sha256sum | cut -d' ' -f1)
+      4. echo "$hash" > .update-state
+      5. bash update.sh
+    Result: "No changes detected. Skipping build and restart." in <2s, exit 0
+    Evidence: .sisyphus/evidence/f1-update-sh-optimization.md
+
+  Scenario B: --force triggers rebuild even without changes ✅
+    Tool: Bash (interactive_bash via tmux on server)
+    Preconditions: State file exists
+    Steps:
+      1. bash update.sh --force
+    Result: "--force flag detected. Will rebuild." → full cycle
+    Evidence: .sisyphus/evidence/f1-update-sh-optimization.md
+
+  Scenario C: .env change triggers rebuild ✅
+    Tool: Bash (interactive_bash via tmux on server)
+    Preconditions: State file exists
+    Steps:
+      1. echo "# test change" >> .env
+      2. bash update.sh
+    Result: "State hash changed. Rebuilding." → full cycle
+    Evidence: .sisyphus/evidence/f1-update-sh-optimization.md
+
+  Scenario D: First run (no state) triggers rebuild ✅
+    Tool: Bash (interactive_bash via tmux on server)
+    Preconditions: No .update-state
+    Steps:
+      1. rm -f .update-state
+      2. bash update.sh
+    Result: "First run (no state file found). Full cycle required." → full cycle
+    Evidence: .sisyphus/evidence/f1-update-sh-optimization.md
+  ```
+
+  **Evidence to Capture**:
+  - [x] Task 1 — skip-rebuild output
+  - [x] Task 1 — force-rebuild output
+  - [x] Task 1 — env-change rebuild output
+  - [x] Task 1 — corrupt-state output
+
+  > Evidence consolidated in `.sisyphus/evidence/f1-update-sh-optimization.md`
+
+  **Commit**: YES
+  - Message: `chore(ops): optimize update.sh to skip rebuild when no changes detected`
+  - Files: `update.sh`, `.gitignore`
+  - Pre-commit: review diff
+
+- [x] 2. Add `.update-state` to `.gitignore`
+
+  **What to do**:
+  - Edit root `.gitignore` to add `.update-state` entry (alongside `connect_remote.txt` on line 41 or nearby)
+  - This prevents accidental commit of machine-local build state
+
+  **Must NOT do**:
+  - Do NOT change any existing `.gitignore` entries
+  - Do NOT add `.update-state` to submodule `.gitignore` files
+
+  **Recommended Agent Profile**:
+  - **Category**: `quick`
+    - Reason: Trivial one-line addition
+  - **Skills**: `[]`
+
+  **Parallelization**:
+  - **Can Run In Parallel**: YES (independent of Task 1's logic, but logically grouped in same commit)
+  - **Blocked By**: Commit groups with Task 1
+
+  **References**:
+  - `.gitignore:41` — Current state, `connect_remote.txt` already listed there
+
+  **Acceptance Criteria**:
+  - [x] `git check-ignore .update-state` returns the path (file is ignored)
+  - [x] No existing entries modified
+
+  **Evidence to Capture**:
+  - [x] git check-ignore verification
+
+  **Commit**: YES (group with Task 1)
+
+---
+
+## Final Verification
+
+- [x] F1. **Behavioral Verification** — Run on server across all scenarios
+
+## Commit Strategy
+
+- **1**: `chore(ops): optimize update.sh to skip rebuild when no changes detected`
+
+## Success Criteria
+
+```bash
+# First run (or after changes): full cycle
+bash update.sh
+# Expected: git pull, down, build, up -d, migrate
+
+# Second run (no changes): skip
+bash update.sh
+# Expected: "No changes detected. Skipping build and restart." in <5s
+
+# Force rebuild
+bash update.sh --force
+# Expected: full cycle regardless
+
+# After .env edit
+bash update.sh
+# Expected: rebuild detected (new .env hash)
+```