@ikieaneh/opencode-kit 0.5.0

package/src/preflight.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# ⛔ opencode-kit preflight — MANDATORY enforcement gate
+# Must run before any tool call. Exits with error if rules violated.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$SCRIPT_DIR/platform.sh"
+
+CONTRACT_KEY="orchestration-contract"
+RULES_FILE=".opencode/rules/rules.json"
+CONTRACT_FILE=".opencode/orchestration/contract.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo "[opencode-kit] ⛔ Pre-flight check..."
+
+# --- Check 1: contract.json exists on disk ---
+if [ ! -f "$CONTRACT_FILE" ]; then
+  echo -e "${RED}⛔ FAILED: $CONTRACT_FILE not found. Run 'opencode-kit init' first.${NC}"
+  exit 1
+fi
+echo "  ✅ contract.json exists"
+
+# --- Check 2: not on main ---
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo -e "${RED}⛔ FAILED: On '$BRANCH' branch. Create a feature branch first.${NC}"
+  echo "  → git checkout -b feature/<YYYYMMDD>-<description>"
+  exit 1
+fi
+echo "  ✅ Branch: $BRANCH (safe)"
+
+# --- Check 3: MCP Availability ---
+echo ""
+echo "  Checking MCP availability..."
+
+MCP_FAIL=0
+
+# 3a. lean-ctx
+LEAN_CTX_AVAILABLE=false
+if command -v lean-ctx &>/dev/null; then
+  echo "  ✅ lean-ctx MCP: available (cli)"
+  LEAN_CTX_AVAILABLE=true
+elif lean-ctx ctx_knowledge recall --query "$CONTRACT_KEY" &>/dev/null; then
+  echo "  ✅ lean-ctx MCP: available (tool)"
+  LEAN_CTX_AVAILABLE=true
+else
+  echo -e "${YELLOW}  ⚠️  lean-ctx MCP: NOT DETECTED — contract persistence will fail${NC}"
+  echo -e "${YELLOW}     → Ensure lean-ctx is configured in opencode.json MCP servers${NC}"
+  MCP_FAIL=1
+fi
+
+# 3b. gitnexus
+if npx --yes gitnexus --version &>/dev/null; then
+  echo "  ✅ gitnexus MCP: available"
+elif npx --yes gitnexus list-repos &>/dev/null; then
+  echo "  ✅ gitnexus MCP: available"
+else
+  echo -e "${YELLOW}  ⚠️  gitnexus MCP: NOT DETECTED — impact analysis will fail${NC}"
+  echo -e "${YELLOW}     → Ensure gitnexus is configured in opencode.json MCP servers${NC}"
+  MCP_FAIL=1
+fi
+
+# 3c. graphify (check via gitnexus index since graphify consumes gitnexus data)
+GRAPHIFY_AVAILABLE=false
+if npx --yes gitnexus analyze --help &>/dev/null; then
+  # gitnexus is available — check if index exists
+  GITNEXUS_DIR=$(find . -name "gitnexus-out" -type d 2>/dev/null | head -1)
+  if [ -n "$GITNEXUS_DIR" ]; then
+    echo "  ✅ graphify: available (gitnexus index found)"
+    GRAPHIFY_AVAILABLE=true
+  else
+    echo -e "${YELLOW}  ⚠️  graphify: gitnexus index not built yet. Run: npx gitnexus analyze${NC}"
+  fi
+else
+  echo -e "${YELLOW}  ⚠️  graphify: gitnexus not available — graphify depends on gitnexus index${NC}"
+fi
+
+# 3d. context7 (library docs — soft check, non-blocking)
+if command -v curl &>/dev/null; then
+  echo "  ✅ context7 MCP: curl available (http transport)"
+fi
+
+echo ""
+
+# --- Check 4: rules.json exists ---
+if [ ! -f "$RULES_FILE" ]; then
+  echo -e "${YELLOW}⚠️  WARNING: $RULES_FILE not found. Rules enforcement disabled.${NC}"
+else
+  echo "  ✅ rules.json found"
+fi
+
+# --- Telemetry: record phase start ---
+mkdir -p .opencode/telemetry
+echo $(date +%s) > .opencode/telemetry/.phase_start
+
+# --- Check 5: contract state validation ---
+if [ -n "$PYTHON_CMD" ] && [ -f "$CONTRACT_FILE" ]; then
+  STATE=$($PYTHON_CMD -c "
+import json,sys
+try:
+  with open('$CONTRACT_FILE') as f: d=json.load(f)
+  print(d.get('state','UNKNOWN'))
+except: print('PARSE_ERROR')
+" 2>/dev/null)
+  if [ "$STATE" = "PARSE_ERROR" ] || [ "$STATE" = "UNKNOWN" ]; then
+    echo -e "${YELLOW}  ⚠️  Contract state: unknown — contract.json may be malformed${NC}"
+  else
+    echo "  ✅ Contract state: $STATE"
+  fi
+fi
+
+# --- Final verdict ---
+if [ "$MCP_FAIL" -eq 1 ]; then
+  echo -e "${YELLOW}[opencode-kit] ⛔ Pre-flight completed with WARNINGS. Missing MCPs may cause failures.${NC}"
+else
+  echo "[opencode-kit] ✅ Pre-flight passed. All MCPs available. Proceed."
+fi

package/src/telemetry.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# opencode-kit telemetry — view phase telemetry
+# Usage: bash src/telemetry.sh [--json|--summary|--phases]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$SCRIPT_DIR/platform.sh"
+
+TELEMETRY_DIR=".opencode/telemetry"
+CONTRACT_FILE=".opencode/orchestration/contract.json"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+MODE="${1:-summary}"
+
+echo -e "${CYAN}[opencode-kit] 📊 Telemetry${NC}"
+echo ""
+
+case "$MODE" in
+  --json)
+    if [ -f "$TELEMETRY_DIR/summary.json" ]; then
+      cat "$TELEMETRY_DIR/summary.json"
+    else
+      echo -e "${YELLOW}No telemetry data yet. Run a phase first.${NC}"
+    fi
+    ;;
+  --phases)
+    if [ -f "$TELEMETRY_DIR/phases.jsonl" ]; then
+      echo "Phase transitions:"
+      cat "$TELEMETRY_DIR/phases.jsonl" | while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        FROM=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('from','?'))" 2>/dev/null)
+        TO=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('to','?'))" 2>/dev/null)
+        MS=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('elapsed_ms',0))" 2>/dev/null)
+        printf "  %-20s → %-20s  %5.1fs\n" "$FROM" "$TO" "$(echo "scale=1; $MS/1000" | bc 2>/dev/null || echo "$((MS/1000)).$((MS%1000/100))")"
+      done
+    else
+      echo -e "${YELLOW}No phase data yet.${NC}"
+    fi
+    ;;
+  --summary|*)
+    if [ -f "$TELEMETRY_DIR/summary.json" ]; then
+      TOTAL_S=$($PYTHON_CMD -c "import json; d=json.load(open('$TELEMETRY_DIR/summary.json')); print(d.get('total_elapsed_s',0))" 2>/dev/null || echo "0")
+      PHASES=$($PYTHON_CMD -c "import json; d=json.load(open('$TELEMETRY_DIR/summary.json')); print(len(d.get('phases_completed',[])))" 2>/dev/null || echo "0")
+      echo "  Total elapsed: ${TOTAL_S}s"
+      echo "  Phases completed: $PHASES"
+      echo ""
+      echo "  Latest phases:"
+      tail -5 "$TELEMETRY_DIR/phases.jsonl" 2>/dev/null | while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        TS=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('ts','?'))" 2>/dev/null | cut -dT -f2 | cut -d. -f1)
+        FROM=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('from','?'))" 2>/dev/null)
+        TO=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('to','?'))" 2>/dev/null)
+        MS=$(echo "$line" | $PYTHON_CMD -c "import sys,json; d=json.load(sys.stdin); print(d.get('elapsed_ms',0))" 2>/dev/null)
+        echo "    $TS  $FROM → $TO  ($((MS/1000))s)"
+      done
+    else
+      echo -e "${YELLOW}No telemetry data yet. Run a phase first.${NC}"
+      echo "  Phases are recorded automatically by postflight.sh"
+    fi
+    ;;
+esac

package/src/update.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# opencode-kit update — pull latest templates and scripts from GitHub
+# Preserves existing contract.json state (goal, scope, decisions).
+# Usage: bash src/update.sh [--dry-run] [--version <tag>]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$SCRIPT_DIR/platform.sh"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+DRY_RUN=false
+VERSION="main"
+REPO_URL="https://github.com/RizkiRachman/opencode-kit.git"
+
+# --- Parse args ---
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true; shift ;;
+    --version) VERSION="$2"; shift 2 ;;
+    -v) VERSION="$2"; shift 2 ;;
+    *) echo -e "${RED}Unknown: $1${NC}"; exit 1 ;;
+  esac
+done
+
+echo -e "${CYAN}[opencode-kit] 🔄 Update check${NC}"
+echo "  Current dir: $PWD"
+echo "  Source:      $REPO_URL (branch: $VERSION)"
+echo "  Dry run:     $DRY_RUN"
+echo ""
+
+# --- Check we're in an opencode-kit project ---
+if [ ! -d ".opencode" ]; then
+  echo -e "${RED}❌ No .opencode/ directory found. Are you in an opencode-kit project?${NC}"
+  exit 1
+fi
+
+# --- Clone latest to temp ---
+TEMP_DIR=$(mktemp -d /tmp/opencode-kit-XXXXX)
+echo "  Cloning latest version to $TEMP_DIR..."
+
+if ! git clone --depth 1 --branch "$VERSION" "$REPO_URL" "$TEMP_DIR" 2>/dev/null; then
+  echo -e "${RED}❌ Failed to clone $REPO_URL (branch: $VERSION)${NC}"
+  rm -rf "$TEMP_DIR"
+  exit 1
+fi
+echo "  ✅ Cloned"
+
+# --- Read versions ---
+CURRENT_VERSION=""
+if [ -f ".opencode/orchestration/contract.json" ]; then
+  CURRENT_VERSION=$($PYTHON_CMD -c "
+import json
+with open('.opencode/orchestration/contract.json') as f:
+  d=json.load(f)
+print(d.get('contract_version', 'unknown'))
+" 2>/dev/null || echo "unknown")
+fi
+
+LATEST_VERSION=$($PYTHON_CMD -c "
+import json
+with open('$TEMP_DIR/templates/contract.json') as f:
+  d=json.load(f)
+print(d.get('contract_version', 'unknown'))
+" 2>/dev/null || echo "unknown")
+
+echo "  Current version: $CURRENT_VERSION"
+echo "  Latest version:  $LATEST_VERSION"
+echo ""
+
+if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ] && [ "$VERSION" = "main" ]; then
+  echo -e "${GREEN}✅ Already up to date (v$CURRENT_VERSION)${NC}"
+  rm -rf "$TEMP_DIR"
+  exit 0
+fi
+
+# --- Backup contract state ---
+echo "  Backing up contract state..."
+STATE_BACKUP=$(mktemp /tmp/opencode-contract-state-XXXXX.json)
+$PYTHON_CMD -c "
+import json
+with open('.opencode/orchestration/contract.json') as f:
+  d = json.load(f)
+# Extract only the state fields to preserve
+state = {
+  'requirements': d.get('requirements', {}),
+  'scope': d.get('scope', {}),
+  'decisions': d.get('decisions', {}),
+  'governance': d.get('governance', {}),
+  'metrics': d.get('metrics', {}),
+  'lessons_learned': d.get('lessons_learned', []),
+  'retry': d.get('retry', {}),
+  'score': d.get('score', {}),
+  'outputs': d.get('outputs', {})
+}
+with open('$STATE_BACKUP', 'w') as f:
+  json.dump(state, f, indent=2)
+" 2>/dev/null || echo "  ⚠️  Could not backup contract state"
+echo "  ✅ State backed up"
+
+# --- Files to update ---
+echo ""
+echo "  Files to update:"
+UPDATES=0
+
+update_file() {
+  local src="$1"
+  local dst="$2"
+  local label="$3"
+  if [ -f "$src" ]; then
+    if [ "$DRY_RUN" = true ]; then
+      echo "  [DRY-RUN] Would update: $label"
+    else
+      cp "$src" "$dst"
+      chmod +x "$dst" 2>/dev/null || true
+      echo "  ✅ Updated: $label"
+    fi
+    UPDATES=$((UPDATES + 1))
+  else
+    echo "  ⚠️  Source not found: $src"
+  fi
+}
+
+# Update scripts
+for script in preflight.sh postflight.sh verify.sh adr.sh platform.sh; do
+  update_file "$TEMP_DIR/src/$script" ".opencode/src/$script" "src/$script"
+done
+
+# Update init.sh (for future --force re-inits)
+update_file "$TEMP_DIR/src/init.sh" ".opencode/src/init.sh" "src/init.sh"
+
+# Update update.sh itself
+update_file "$TEMP_DIR/src/update.sh" ".opencode/src/update.sh" "src/update.sh"
+
+# Update rules
+update_file "$TEMP_DIR/rules/rules.json" ".opencode/rules/rules.json" "rules/rules.json"
+update_file "$TEMP_DIR/rules/validation.sh" ".opencode/rules/validation.sh" "rules/validation.sh"
+
+# Update agent templates (but NOT contract.json — preserve state)
+for agent in orchestrator planner task-manager code-reviewer learner fixer; do
+  update_file "$TEMP_DIR/templates/agents/$agent.md" ".opencode/agents/$agent.md" "agents/$agent.md"
+done
+
+# Update superpowers contract template
+update_file "$TEMP_DIR/templates/superpowers-contract.json" ".opencode/templates/superpowers-contract.json" "superpowers-contract.json"
+
+# --- Restore contract state ---
+if [ "$DRY_RUN" = false ] && [ -f "$STATE_BACKUP" ]; then
+  $PYTHON_CMD -c "
+import json
+with open('.opencode/orchestration/contract.json') as f:
+  contract = json.load(f)
+with open('$STATE_BACKUP') as f:
+  state = json.load(f)
+# Merge preserved state back into new contract
+for key, val in state.items():
+  if val:  # only overwrite if backup has data
+    contract[key] = val
+# Update contract_version to latest
+contract['contract_version'] = '$LATEST_VERSION'
+with open('.opencode/orchestration/contract.json', 'w') as f:
+  json.dump(contract, f, indent=2)
+" 2>/dev/null && echo "  ✅ Contract state restored" || echo "  ⚠️  Contract state restore failed"
+fi
+
+# --- Cleanup ---
+rm -rf "$TEMP_DIR" "$STATE_BACKUP"
+
+# --- Summary ---
+echo ""
+if [ "$DRY_RUN" = true ]; then
+  echo -e "${YELLOW}[opencode-kit] 🔄 Dry run complete. $UPDATES files would be updated.${NC}"
+else
+  echo -e "${GREEN}[opencode-kit] ✅ Update complete. $UPDATES files updated.${NC}"
+  echo "  Run .opencode/src/verify.sh to verify installation."
+fi

package/src/verify.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# opencode-kit verify — check installation health
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "[opencode-kit] 🔍 Verify: checking installation..."
+FAIL=0
+
+# --- Check 1: required files exist ---
+for f in \
+  ".opencode/orchestration/contract.json" \
+  ".opencode/rules/rules.json" \
+  ".opencode/templates/superpowers-contract.json"; do
+  if [ -f "$f" ]; then
+    echo "  ✅ $f"
+  else
+    echo "  ❌ $f MISSING"
+    FAIL=1
+  fi
+done
+
+# --- Check 2: agent .md files exist ---
+for agent in orchestrator planner task-manager code-reviewer learner fixer; do
+  FILE=".opencode/agents/$agent.md"
+  if [ -f "$FILE" ]; then
+    # Check pre-flight gate exists in file
+    if grep -q "load contract" "$FILE" 2>/dev/null; then
+      echo "  ✅ agents/$agent.md (has pre-flight gate)"
+    else
+      echo "  ⚠️  agents/$agent.md (MISSING pre-flight gate)"
+    fi
+  else
+    echo "  ❌ agents/$agent.md MISSING"
+    FAIL=1
+  fi
+done
+
+# --- Check 3: telemetry directory ---
+mkdir -p .opencode/telemetry 2>/dev/null
+echo "  ✅ telemetry directory ready"
+
+# --- Check 4: scripts executable ---
+for script in ".opencode/src/preflight.sh" ".opencode/src/postflight.sh" ".opencode/src/telemetry.sh"; do
+  if [ -x "$script" ]; then
+    echo "  ✅ $script (executable)"
+  elif [ -f "$script" ]; then
+    echo "  ⚠️  $script (not executable — run chmod +x)"
+  else
+    echo "  ❌ $script MISSING"
+    FAIL=1
+  fi
+done
+
+# --- Check 5: not on main ---
+BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "  ⚠️  On '$BRANCH' branch — create a feature branch"
+fi
+echo "  ℹ️  Branch: $BRANCH"
+
+if [ "$FAIL" -eq 1 ]; then
+  echo "[opencode-kit] ❌ Verify FAILED — run 'opencode-kit init' to repair"
+  exit 1
+fi
+
+echo "[opencode-kit] ✅ All checks passed"

package/templates/agents/code-reviewer.md

@@ -0,0 +1,88 @@
+---
+description: Read-only code review — quality, security, performance, DevOps. No edits.
+mode: subagent
+temperature: 0.1
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
+  webfetch: allow
+  edit: deny
+  bash:
+    "*": ask
+    "git diff*": allow
+    "git log*": allow
+    "mvn test*": allow
+    "mvn compile*": allow
+    "mvn verify": allow
+  task:
+    "*": deny
+---
+
+## ⛔ PRE-FLIGHT GATE — DO NOT SKIP
+
+```
+1. Load contract: lean-ctx ctx_knowledge recall --query "orchestration-contract"
+   → Extract: requirements.*, governance.*, outputs.code_changes[]
+   → If empty → STOP
+
+2. Validate state: Must be REVIEW
+   → If wrong state → STOP
+
+3. Read rules.json: Understand what rules to check against
+```
+
+## Permissions
+- Read: All project files
+- Write: None (strictly read-only)
+- Cannot: Edit files, spawn subagents
+
+You are a read-only code reviewer. You never make edits.
+
+## Four Lenses
+
+### 1. Code Quality & SOLID
+- SOLID violations, god classes, feature envy
+- Duplicate code, dead code, TODOs
+- Naming clarity, proper abstractions
+
+### 2. Security
+- Input validation, injection, XSS, CSRF
+- AuthZ checked on every endpoint?
+- Secrets in code, config, logs?
+
+### 3. Performance & Reliability
+- N+1 queries, missing indexes, no pagination
+- Timeout handling, retry with backoff
+- Race conditions, deadlocks
+
+### 4. DevOps Operability
+- Zero-downtime deploy? Backward-compatible migrations?
+- New env vars documented? Observability adequate?
+
+## Report Format
+```json
+{
+  "verdict": "PASS|FLAG|BLOCK",
+  "findings": {
+    "critical": [{ "file": "path:line", "impact": "...", "recommendation": "..." }],
+    "high": [],
+    "medium": [],
+    "low": []
+  },
+  "summary": "X critical, Y high, Z medium, W low",
+  "lens_coverage": {
+    "code_quality": "red|yellow|green",
+    "security": "red|yellow|green",
+    "performance": "red|yellow|green",
+    "devops": "red|yellow|green"
+  },
+  "blast_radius_verified": true
+}
+```
+
+**Verdict rules:**
+- `PASS` — no critical/high findings
+- `FLAG` — has high findings, needs discussion
+- `BLOCK` — has critical findings or architecture violations

package/templates/agents/fixer.md

@@ -0,0 +1,56 @@
+---
+description: Fast implementation specialist for well-defined bounded tasks. Read/write files, scoped edits only.
+mode: subagent
+temperature: 0.1
+permission:
+  read: allow
+  edit: allow
+  write: allow
+  glob: allow
+  grep: allow
+  list: allow
+  bash:
+    "*": ask
+    "mvn spotless:apply": allow
+    "mvn test*": allow
+    "mvn compile*": allow
+    "git diff*": allow
+  task:
+    "*": deny
+---
+
+## ⛔ PRE-FLIGHT GATE — DO NOT SKIP
+
+```
+1. Load contract: lean-ctx ctx_knowledge recall --query "orchestration-contract"
+   → Extract: decisions.*, governance.*, scope.included
+   → If empty → STOP
+
+2. Check branch: git branch --show-current
+   → If main/master: STOP
+
+3. Read scope: scope.included defines what you may modify
+   → Do NOT touch files outside scope
+```
+
+## Permissions
+- Read: All project files
+- Write: Scoped to assigned task only
+- Execute: mvn spotless:apply, mvn test/compile, git diff
+- Cannot: Spawn subagents, push to git, modify CI/CD
+
+You are a **fast implementation specialist for well-defined bounded tasks**. You do NOT research, make decisions, or expand scope.
+
+## Process
+1. Read assigned scope only
+2. Follow project conventions (writing order, naming)
+3. Make changes efficiently
+4. Run spotless:apply + mvn compile on affected modules
+5. Do NOT expand scope or make unsolicited improvements
+
+## Output Format
+Return concise report:
+1. Files modified (paths + line ranges)
+2. Summary of changes per file
+3. Test results (compile/test pass/fail)
+4. Any risks introduced or deviations from spec

package/templates/agents/learner.md

@@ -0,0 +1,87 @@
+---
+description: Post-execution learning agent. Extracts lessons, persists knowledge, updates all memory systems.
+mode: subagent
+temperature: 0.3
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
+  edit: deny
+  bash:
+    "*": ask
+    "git diff*": allow
+    "git log*": allow
+  task:
+    "*": deny
+---
+
+## ⛔ PRE-FLIGHT GATE — DO NOT SKIP
+
+```
+1. Load contract: lean-ctx ctx_knowledge recall --query "orchestration-contract"
+   → Extract ALL fields: session, requirements, decisions, outputs, score, metrics, retry, lessons_learned[]
+   → If empty → STOP. Cannot analyze without contract.
+
+2. Sync ALL memory systems before analysis:
+   - STATE.md, PROJECT.md, AGENTS.md
+   - lean-ctx knowledge (recall architecture, conventions, testing)
+   - gitnexus: re-index + detect_changes
+   - graphify: check stats
+   - git log --oneline -10
+   - git diff main...HEAD --stat
+
+3. Read rules.json: Check LEARN_001 (must update ALL 11 memory systems)
+```
+
+## Permissions
+- Read: All project files
+- Write: None (read-only analysis)
+- Cannot: Edit files, run builds, spawn subagents
+
+You are the **learner agent** — the last agent called. You turn every completed task into durable knowledge.
+
+## Mandatory: Update ALL Memory Systems
+
+| System | Tool | What to Do |
+|--------|------|------------|
+| lean-ctx knowledge | `ctx_knowledge remember` | Persist gotchas, patterns, decisions |
+| STATE.md | Note updates needed | Append completed work, update focus |
+| Orchestration contract | `ctx_knowledge remember --key orchestration-contract` | Set state=COMPLETE, append lessons |
+| gitnexus | `npx gitnexus analyze` | Re-index code intelligence |
+| graphify | Auto-consumes gitnexus | Verify via graphify_graph_stats |
+| Handoff pack | Via memory-mcp | Label: handoff.learner.<task_id> |
+| ctx_session | `ctx_session save` | Persist conversation |
+
+## Analysis Process
+
+### Step 1: Review what happened
+- Read git diff, contract, test results
+- Check: Did plan match execution?
+
+### Step 2: Extract learnings
+- **What went well** (1-3) — reinforce as patterns
+- **What went wrong** (1-3) — prevent recurrence
+- **What to change next time** (1-2) — concrete, actionable
+
+### Step 3: Persist knowledge
+- Gotchas → `ctx_knowledge remember category gotchas`
+- Patterns → `ctx_knowledge remember category architecture`
+- Decisions → `ctx_knowledge remember category architecture`
+
+### 4. Output Format
+```json
+{
+  "lessons_learned": ["..."],
+  "knowledge_updates": [
+    { "category": "gotchas", "key": "...", "value": "...", "severity": "warning" }
+  ],
+  "next_session_tips": "...",
+  "docs_updated": [],
+  "envelope_updates": {
+    "state": "COMPLETE",
+    "score_combined": 0,
+    "phases_completed": []
+  }
+}
+```