Add update mechanism: update.sh script, project upgrade option in onboarding, update instructions in README, Bug 12

BUG_REPORT.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-A comprehensive review of the agent-framework project identified **11 bugs** (after removing the visualize*.html files, which eliminated 8 visualization-related bugs). Remaining issues range from critical (Orchestrator is not a real state machine) to low (unused placeholders).
+A comprehensive review of the agent-framework project identified **12 bugs** (after removing the visualize*.html files, which eliminated 8 visualization-related bugs). Remaining issues range from critical (Orchestrator is not a real state machine) to low (unused placeholders).
 
 ---
 
@@ -103,6 +103,13 @@ A comprehensive review of the agent-framework project identified **11 bugs** (af
 - **Reproduction**: Read `prompts/orchestrate.md`; the "Tasks from bug verdicts" section says "MUST also create new tasks and drive them" in Autopilot mode, but the note says "the Orchestrator should NOT create fix/review/tiebreak tasks from FAIL/NEEDS_REVIEW verdicts — it should pause and let the user decide".
 - **Suggested Fix**: **RESOLVED** — Split the section into Manual Mode (create tasks) and Autopilot Mode (pause and report human intervention required).
 
+### Bug 12: No update mechanism for existing projects
+- **Severity**: Medium
+- **Location**: `README.md`, `install.sh`, `prompts/onboarding.md`
+- **Description**: There is no mechanism to update an existing project's framework files when the global framework is updated. The README mentions "Upgrade" as a project type in the onboarding section but has no implementation. The install.sh only mentions `git pull` as a vague update hint. When the framework adds new phases (e.g., Doc Review), existing projects won't have the new prompt files and won't know about them.
+- **Reproduction**: User updates the global framework with new phases. Existing projects still only have the old prompt files. The agent doesn't know about the new phases for those projects.
+- **Suggested Fix**: **RESOLVED** — Added `update.sh` script for updating the global framework, added "Upgrade" option in onboarding prompt for existing projects, updated README with update instructions.
+
 ---
 
 ## Score
@@ -120,4 +127,5 @@ A comprehensive review of the agent-framework project identified **11 bugs** (af
 | 9   | High     | +5    | **RESOLVED** — Dedicated Doc Review phase added between Adversarial Bug Find and Referee |
 | 10  | High     | +5    | **RESOLVED** — Research and Design phases now interactive with user |
 | 11  | Medium   | +5    | **RESOLVED** — Split Orchestrator verdict task creation into Manual/Autopilot modes |
-| **Total** | | **47** | |
+| 12  | Medium   | +5    | **RESOLVED** — Added `update.sh` script, upgrade option in onboarding, update instructions in README |
+| **Total** | | **52** | |

README.md

@@ -21,6 +21,22 @@ chmod +x install.sh
 ```
 *Note: This creates the "brain" of the framework (prompts, state machines, and rules) in your home directory.*
 
+### Updating the Framework
+
+When the framework is updated, you can update your global installation:
+
+```bash
+cd ~/.agent-framework
+./update.sh
+```
+
+This will:
+- Fetch the latest changes from the repository
+- Check for uncommitted changes and warn you
+- Pull the latest updates
+
+**Upgrading existing projects:** When the framework is updated, existing projects may need their framework files upgraded (new phases added, new prompts, etc.). To upgrade an existing project, tell the agent: "Upgrade the agent-framework for this project." The agent will check for missing files and update them.
+
 ---
 
 ## 2. Project Setup (Per project)

install.sh

@@ -5,7 +5,7 @@ FRAMEWORK_DIR="$HOME/.agent-framework"
 
 if [ -d "$FRAMEWORK_DIR" ]; then
   echo "agent-framework already installed at $FRAMEWORK_DIR"
-  echo "Run 'cd $FRAMEWORK_DIR && git pull' to update."
+  echo "Run './update.sh' to update."
   exit 0
 fi
 

prompts/onboarding.md

@@ -15,6 +15,16 @@ Your only job is to set up the minimal agent framework structure in the target p
 
 ## Onboarding Ritual (Strict Sequence)
 
+### Step 0: Check if Framework Needs Upgrade
+
+Before proceeding, check if the project is running an older version of the framework:
+1. Check if `~/.agent-framework/prompts/workflow.md` exists and compare its content with the current global framework's workflow.md.
+2. If the project's `~/.agent-framework/` has a `workflow.md` that differs from the current global version, the project needs an upgrade.
+3. If the project's `~/.agent-framework/` is missing new prompt files (e.g., `doc_review.md`), the project needs an upgrade.
+4. If an upgrade is needed, report it to the user and offer to upgrade the project's framework files.
+
+### Step 1: Discovery
+
 1. Check if {project}/.agent-framework/ exists. If not, create it.
 2. Ensure exactly two files exist inside it:
    - AGENT.md (project-level router)
@@ -39,6 +49,7 @@ Then produce a file called ONBOARDING_REPORT.md at {project}/tasks/onboarding/ON
 - What process this project expects
 - Key observations from the project structure
 - Any missing pieces the human should provide next
+- **Upgrade status**: Whether the project's framework files are up to date with the global framework
 
 When the ritual is complete, output "CONTRACT_MET" and stop.
 
@@ -50,3 +61,24 @@ Do not begin any research, implementation, or bug-finding tasks.
 - Keep everything minimal. Only create the two required files.
 - Never copy the entire global framework into the project.
 - This is a one-time setup. After this session the normal research → implement flow takes over.
+
+---
+
+## Project Upgrade
+
+When a user asks to "upgrade the agent-framework for this project," the agent should:
+
+1. Compare the project's `~/.agent-framework/` files with the global `~/.agent-framework/` files.
+2. Identify any missing files in the project's framework directory:
+   - New prompt files (e.g., `doc_review.md`)
+   - Updated `workflow.md` (state machine changes)
+   - New contract files
+3. Add the missing files from the global framework into the project's framework directory.
+4. Do NOT overwrite existing project-specific files (AGENT.md, RULES.md).
+5. Report what was upgraded and what was already up to date.
+
+Example upgrade scenario:
+- User says: "Upgrade the agent-framework for this project"
+- Agent detects that `prompts/doc_review.md` is missing from the project's framework
+- Agent copies `prompts/doc_review.md` from the global framework into the project's framework
+- Agent reports: "Upgraded: Added prompts/doc_review.md. Your framework is now up to date."

update.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+set -e
+
+FRAMEWORK_DIR="$HOME/.agent-framework"
+
+if [ ! -d "$FRAMEWORK_DIR" ]; then
+  echo "ERROR: agent-framework not installed at $FRAMEWORK_DIR"
+  echo "Run './install.sh' first."
+  exit 1
+fi
+
+echo "Updating agent-framework at $FRAMEWORK_DIR..."
+cd "$FRAMEWORK_DIR"
+
+# Check if it's a git repo
+if [ ! -d ".git" ]; then
+  echo "ERROR: $FRAMEWORK_DIR is not a git repository."
+  echo "Cannot update. Please reinstall from git."
+  exit 1
+fi
+
+# Fetch latest changes
+git fetch origin
+echo ""
+
+# Check for local changes
+if ! git diff --quiet HEAD; then
+  echo "WARNING: You have uncommitted changes in $FRAMEWORK_DIR."
+  echo "These will be lost when pulling updates."
+  read -p "Do you want to discard your local changes and update? (y/N) " -n 1 -r
+  echo
+  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Update cancelled."
+    exit 1
+  fi
+  git reset --hard HEAD
+fi
+
+# Pull latest changes
+git pull origin main
+echo ""
+
+echo "Update complete."
+echo "You can check for breaking changes at: https://gitea.yourdomain.com/hermes/agent-framework"