merge: incorporate origin/main into community-mode branch

Conflicts resolved: - README.md: merge skill lists — keep /gstack-submit from our branch, add /plan-devex-review, /devex-review, /pair-agent from main. Accept main's team mode step 2 text. - setup: keep both our install ping (step 9) and main's team mode hook registration (step 10) - supabase/functions/telemetry-ingest/index.ts: keep our deletion (dead code removed earlier on this branch, main modified it) Main brought in: team mode (--team flag, auto-update hook, session tracking), /plan-devex-review + /devex-review skills, /pair-agent skill, open-gstack-browser, /checkpoint, /health, /humanizer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-05-10 23:14:56 +02:00 · 2026-04-07 20:29:53 -10:00
parent 30e6747814 9d34baa973
commit d519678916
217 changed files with 39025 additions and 2201 deletions
@@ -291,7 +291,7 @@ function extractCwdFromJsonl(filePath: string): string | null {
 }

 function scanCodex(since: Date): Session[] {
-  const sessionsDir = join(homedir(), ".codex", "sessions");
+  const sessionsDir = process.env.CODEX_SESSIONS_DIR || join(homedir(), ".codex", "sessions");
  if (!existsSync(sessionsDir)) return [];

  const sessions: Session[] = [];
@@ -326,11 +326,14 @@ function scanCodex(since: Date): Session[] {
              continue;
            }

-            // Read first line for session_meta (only first 4KB)
+            // Codex session_meta lines embed the full system prompt in
+            // base_instructions (~15KB as of CLI v0.117+). A 4KB buffer
+            // truncates the line and JSON.parse fails. 128KB covers current
+            // sizes with room for growth.
            try {
              const fd = openSync(filePath, "r");
-              const buf = Buffer.alloc(4096);
-              const bytesRead = readSync(fd, buf, 0, 4096, 0);
+              const buf = Buffer.alloc(131072);
+              const bytesRead = readSync(fd, buf, 0, 131072, 0);
              closeSync(fd);
              const firstLine = buf.toString("utf-8", 0, bytesRead).split("\n")[0];
              if (!firstLine) continue;
@@ -43,13 +43,14 @@ if [ ${#FILES[@]} -eq 0 ]; then
 fi

 # Process all files through bun for JSON parsing, decay, dedup, filtering
-cat "${FILES[@]}" 2>/dev/null | bun -e "
+GSTACK_SEARCH_TYPE="$TYPE" GSTACK_SEARCH_QUERY="$QUERY" GSTACK_SEARCH_LIMIT="$LIMIT" GSTACK_SEARCH_SLUG="$SLUG" GSTACK_SEARCH_CROSS="$CROSS_PROJECT" \
+cat "${FILES[@]}" 2>/dev/null | GSTACK_SEARCH_TYPE="$TYPE" GSTACK_SEARCH_QUERY="$QUERY" GSTACK_SEARCH_LIMIT="$LIMIT" GSTACK_SEARCH_SLUG="$SLUG" GSTACK_SEARCH_CROSS="$CROSS_PROJECT" bun -e "
 const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
 const now = Date.now();
-const type = '${TYPE}';
-const query = '${QUERY}'.toLowerCase();
-const limit = ${LIMIT};
-const slug = '${SLUG}';
+const type = process.env.GSTACK_SEARCH_TYPE || '';
+const query = (process.env.GSTACK_SEARCH_QUERY || '').toLowerCase();
+const limit = parseInt(process.env.GSTACK_SEARCH_LIMIT || '10', 10);
+const slug = process.env.GSTACK_SEARCH_SLUG || '';

 const entries = [];
 for (const line of lines) {
@@ -67,7 +68,7 @@ for (const line of lines) {

    // Determine if this is from the current project or cross-project
    // Cross-project entries are tagged for display
-    e._crossProject = !line.includes(slug) && '${CROSS_PROJECT}' === 'true';
+    e._crossProject = !line.includes(slug) && process.env.GSTACK_SEARCH_CROSS === 'true';

    entries.push(e);
  } catch {}
@@ -2,19 +2,26 @@
 set -euo pipefail

 # gstack-platform-detect: show which AI coding agents are installed and gstack status
+# Config-driven: reads host definitions from hosts/*.ts via host-config-export.ts
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+GSTACK_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
 printf "%-16s %-10s %-40s %s\n" "Agent" "Version" "Skill Path" "gstack"
 printf "%-16s %-10s %-40s %s\n" "-----" "-------" "----------" "------"
-for entry in "claude:claude" "codex:codex" "droid:factory" "kiro-cli:kiro"; do
-  bin="${entry%%:*}"; label="${entry##*:}"
-  if command -v "$bin" >/dev/null 2>&1; then
-    ver=$("$bin" --version 2>/dev/null | head -1 || echo "unknown")
-    case "$label" in
-      claude)  spath="$HOME/.claude/skills/gstack" ;;
-      codex)   spath="$HOME/.codex/skills/gstack" ;;
-      factory) spath="$HOME/.factory/skills/gstack" ;;
-      kiro)    spath="$HOME/.kiro/skills/gstack" ;;
-    esac
-    status=$([ -d "$spath" ] && echo "INSTALLED" || echo "NOT INSTALLED")
-    printf "%-16s %-10s %-40s %s\n" "$label" "$ver" "$spath" "$status"
+
+for host in $(bun run "$GSTACK_DIR/scripts/host-config-export.ts" list 2>/dev/null); do
+  cmd=$(bun run "$GSTACK_DIR/scripts/host-config-export.ts" get "$host" cliCommand 2>/dev/null)
+  root=$(bun run "$GSTACK_DIR/scripts/host-config-export.ts" get "$host" globalRoot 2>/dev/null)
+  spath="$HOME/$root"
+
+  if command -v "$cmd" >/dev/null 2>&1; then
+    ver=$("$cmd" --version 2>/dev/null | head -1 || echo "unknown")
+    if [ -d "$spath" ] || [ -L "$spath" ]; then
+      status="INSTALLED"
+    else
+      status="NOT INSTALLED"
+    fi
+    printf "%-16s %-10s %-40s %s\n" "$host" "$ver" "$spath" "$status"
  fi
 done
@@ -36,6 +36,16 @@ SKILLS_DIR="${GSTACK_SKILLS_DIR:-$(dirname "$INSTALL_DIR")}"
 # Read prefix setting
 PREFIX=$("$GSTACK_CONFIG" get skill_prefix 2>/dev/null || echo "false")

+# Helper: remove old skill entry (symlink or real directory with symlinked SKILL.md)
+_cleanup_skill_entry() {
+  local entry="$1"
+  if [ -L "$entry" ]; then
+    rm -f "$entry"
+  elif [ -d "$entry" ] && [ -L "$entry/SKILL.md" ]; then
+    rm -rf "$entry"
+  fi
+}
+
 # Discover skills (directories with SKILL.md, excluding meta dirs)
 SKILL_COUNT=0
 for skill_dir in "$INSTALL_DIR"/*/; do
@@ -51,18 +61,22 @@ for skill_dir in "$INSTALL_DIR"/*/; do
      gstack-*) link_name="$skill" ;;
      *)        link_name="gstack-$skill" ;;
    esac
-    ln -sfn "$INSTALL_DIR/$skill" "$SKILLS_DIR/$link_name"
-    # Remove old flat symlink if it exists (and isn't the same as the new link)
-    [ "$link_name" != "$skill" ] && [ -L "$SKILLS_DIR/$skill" ] && rm -f "$SKILLS_DIR/$skill"
+    # Remove old flat entry if it exists (and isn't the same as the new link)
+    [ "$link_name" != "$skill" ] && _cleanup_skill_entry "$SKILLS_DIR/$skill"
  else
-    # Create flat symlink, remove gstack-* if exists
-    ln -sfn "$INSTALL_DIR/$skill" "$SKILLS_DIR/$skill"
+    link_name="$skill"
    # Don't remove gstack-* dirs that are their real name (e.g., gstack-upgrade)
    case "$skill" in
      gstack-*) ;; # Already the real name, no old prefixed link to clean
-      *)        [ -L "$SKILLS_DIR/gstack-$skill" ] && rm -f "$SKILLS_DIR/gstack-$skill" ;;
+      *)        _cleanup_skill_entry "$SKILLS_DIR/gstack-$skill" ;;
    esac
  fi
+  target="$SKILLS_DIR/$link_name"
+  # Upgrade old directory symlinks to real directories
+  [ -L "$target" ] && rm -f "$target"
+  # Create real directory with symlinked SKILL.md (absolute path)
+  mkdir -p "$target"
+  ln -snf "$INSTALL_DIR/$skill/SKILL.md" "$target/SKILL.md"
  SKILL_COUNT=$((SKILL_COUNT + 1))
 done

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# gstack-session-update — auto-update gstack on session start (team mode)
+#
+# Called by Claude Code SessionStart hook. Must be fast, silent, non-fatal.
+# The entire update runs in background (forked). The hook itself exits
+# immediately so session startup is never delayed.
+#
+# Exit 0 always — errors must never block a Claude Code session.
+
+set +e
+
+GSTACK_DIR="${GSTACK_DIR:-$HOME/.claude/skills/gstack}"
+STATE_DIR="${GSTACK_STATE_DIR:-$HOME/.gstack}"
+THROTTLE_FILE="$STATE_DIR/.last-session-update"
+LOCK_DIR="$STATE_DIR/.setup-lock"
+LOG_FILE="$STATE_DIR/analytics/session-update.log"
+THROTTLE_SECONDS=3600  # 1 hour
+
+log_entry() {
+  mkdir -p "$(dirname "$LOG_FILE")"
+  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $1" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+# ── Guard: gstack must be a git repo ──
+if [ ! -d "$GSTACK_DIR/.git" ]; then
+  exit 0
+fi
+
+# ── Guard: team mode must be enabled ──
+AUTO=$("$GSTACK_DIR/bin/gstack-config" get auto_upgrade 2>/dev/null || true)
+if [ "$AUTO" != "true" ]; then
+  exit 0
+fi
+
+# ── Throttle: skip if checked recently ──
+if [ -f "$THROTTLE_FILE" ]; then
+  LAST=$(cat "$THROTTLE_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  ELAPSED=$(( NOW - LAST ))
+  if [ "$ELAPSED" -lt "$THROTTLE_SECONDS" ]; then
+    exit 0
+  fi
+fi
+
+# ── Fork to background: zero latency on session start ──
+(
+  # Prevent git from prompting for credentials (would hang the background process)
+  export GIT_TERMINAL_PROMPT=0
+
+  mkdir -p "$STATE_DIR"
+
+  # ── Acquire lockfile (skip if another session is running setup) ──
+  if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    # Lock exists — check if stale (PID dead)
+    if [ -f "$LOCK_DIR/pid" ]; then
+      LOCK_PID=$(cat "$LOCK_DIR/pid" 2>/dev/null || echo 0)
+      if [ "$LOCK_PID" -gt 0 ] 2>/dev/null && ! kill -0 "$LOCK_PID" 2>/dev/null; then
+        # Stale lock — remove and re-acquire
+        rm -rf "$LOCK_DIR" 2>/dev/null
+        mkdir "$LOCK_DIR" 2>/dev/null || { log_entry "SKIP lock_contested"; exit 0; }
+      else
+        log_entry "SKIP locked_by=$LOCK_PID"
+        exit 0
+      fi
+    else
+      log_entry "SKIP locked_no_pid"
+      exit 0
+    fi
+  fi
+
+  # Write PID for stale lock detection
+  echo $$ > "$LOCK_DIR/pid" 2>/dev/null
+
+  # Clean up lock on exit
+  trap 'rm -rf "$LOCK_DIR" 2>/dev/null' EXIT
+
+  # ── Pull latest ──
+  OLD_HEAD=$(git -C "$GSTACK_DIR" rev-parse HEAD 2>/dev/null)
+  git -C "$GSTACK_DIR" pull --ff-only -q 2>/dev/null
+  PULL_EXIT=$?
+  NEW_HEAD=$(git -C "$GSTACK_DIR" rev-parse HEAD 2>/dev/null)
+
+  # Record check time regardless of outcome
+  date +%s > "$THROTTLE_FILE" 2>/dev/null
+
+  if [ "$PULL_EXIT" -ne 0 ]; then
+    log_entry "PULL_FAILED exit=$PULL_EXIT"
+    exit 0
+  fi
+
+  # ── If HEAD moved, run setup -q ──
+  if [ "$OLD_HEAD" != "$NEW_HEAD" ]; then
+    log_entry "UPDATING old=$OLD_HEAD new=$NEW_HEAD"
+
+    # bun must be available for setup
+    if command -v bun >/dev/null 2>&1; then
+      ( cd "$GSTACK_DIR" && ./setup -q ) >/dev/null 2>&1 || {
+        log_entry "SETUP_FAILED"
+      }
+    else
+      log_entry "SETUP_SKIPPED bun_missing"
+    fi
+
+    # Write marker so next skill preamble shows "just upgraded"
+    OLD_VER=$(git -C "$GSTACK_DIR" show "$OLD_HEAD:VERSION" 2>/dev/null || echo "unknown")
+    echo "$OLD_VER" > "$STATE_DIR/just-upgraded-from" 2>/dev/null
+    rm -f "$STATE_DIR/last-update-check" 2>/dev/null
+    rm -f "$STATE_DIR/update-snoozed" 2>/dev/null
+
+    log_entry "UPDATED from=$OLD_VER to=$(cat "$GSTACK_DIR/VERSION" 2>/dev/null || echo unknown)"
+  else
+    log_entry "UP_TO_DATE head=$OLD_HEAD"
+  fi
+) &
+
+exit 0
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# gstack-settings-hook — add/remove SessionStart hooks in Claude Code settings.json
+#
+# Usage:
+#   gstack-settings-hook add <hook-command>     # add SessionStart hook
+#   gstack-settings-hook remove <hook-command>  # remove SessionStart hook
+#
+# Requires: bun (already a gstack hard dependency)
+# Writes atomically: .tmp + rename to prevent corruption on crash/disk-full.
+
+set -euo pipefail
+
+ACTION="${1:-}"
+HOOK_CMD="${2:-}"
+SETTINGS_FILE="${GSTACK_SETTINGS_FILE:-$HOME/.claude/settings.json}"
+
+if [ -z "$ACTION" ] || [ -z "$HOOK_CMD" ]; then
+  echo "Usage: gstack-settings-hook {add|remove} <hook-command>" >&2
+  exit 1
+fi
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Error: bun is required but not installed." >&2
+  exit 1
+fi
+
+case "$ACTION" in
+  add)
+    bun -e "
+      const fs = require('fs');
+      const settingsPath = '$SETTINGS_FILE';
+      const hookCmd = $(printf '%s' "$HOOK_CMD" | bun -e "process.stdout.write(JSON.stringify(require('fs').readFileSync('/dev/stdin','utf8')))");
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+      // Dedup: check if hook command already registered
+      const exists = settings.hooks.SessionStart.some(entry =>
+        entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gstack-session-update'))
+      );
+
+      if (!exists) {
+        settings.hooks.SessionStart.push({
+          hooks: [{ type: 'command', command: hookCmd }]
+        });
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    ;;
+  remove)
+    [ -f "$SETTINGS_FILE" ] || exit 0
+    bun -e "
+      const fs = require('fs');
+      const settingsPath = '$SETTINGS_FILE';
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { process.exit(0); }
+
+      if (settings.hooks && settings.hooks.SessionStart) {
+        settings.hooks.SessionStart = settings.hooks.SessionStart.filter(entry =>
+          !(entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gstack-session-update')))
+        );
+        if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    ;;
+  *)
+    echo "Unknown action: $ACTION (expected add or remove)" >&2
+    exit 1
+    ;;
+esac
@@ -6,13 +6,42 @@
 # Security: output is sanitized to [a-zA-Z0-9._-] only, preventing
 # shell injection when consumed via source or eval.
 set -euo pipefail
-RAW_SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-') || true
-RAW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-') || true
-# Strip any characters that aren't alphanumeric, dot, hyphen, or underscore
-SLUG=$(printf '%s' "${RAW_SLUG:-}" | tr -cd 'a-zA-Z0-9._-')
-BRANCH=$(printf '%s' "${RAW_BRANCH:-}" | tr -cd 'a-zA-Z0-9._-')
-# Fallback when git context is absent
+
+CACHE_DIR="$HOME/.gstack/slug-cache"
+PROJECT_DIR="$(pwd)"
+# Encode absolute path as cache key: /Users/j/foo → _Users_j_foo
+CACHE_KEY=$(printf '%s' "$PROJECT_DIR" | tr '/' '_')
+CACHE_FILE="${CACHE_DIR}/${CACHE_KEY}"
+
+# 1. Try cached slug first (guarantees consistency across sessions)
+if [[ -f "$CACHE_FILE" ]]; then
+  SLUG=$(cat "$CACHE_FILE")
+fi
+
+# 2. If no cache, compute from git remote (separated from pipeline to avoid
+#    pipefail swallowing the error and producing an empty slug)
+if [[ -z "${SLUG:-}" ]]; then
+  REMOTE_URL=$(git remote get-url origin 2>/dev/null) || REMOTE_URL=""
+  if [[ -n "$REMOTE_URL" ]]; then
+    RAW_SLUG=$(printf '%s' "$REMOTE_URL" | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
+    SLUG=$(printf '%s' "$RAW_SLUG" | tr -cd 'a-zA-Z0-9._-')
+  fi
+fi
+
+# 3. Fallback to basename only when there's truly no git remote configured
 SLUG="${SLUG:-$(basename "$PWD" | tr -cd 'a-zA-Z0-9._-')}"
+
+# 4. Cache the slug for future sessions (atomic write, fail silently)
+if [[ -n "$SLUG" ]]; then
+  mkdir -p "$CACHE_DIR" 2>/dev/null || true
+  CACHE_TMP=$(mktemp "$CACHE_DIR/.slug-XXXXXX" 2>/dev/null) || CACHE_TMP=""
+  if [[ -n "$CACHE_TMP" ]]; then
+    printf '%s' "$SLUG" > "$CACHE_TMP" && mv "$CACHE_TMP" "$CACHE_FILE" 2>/dev/null || rm -f "$CACHE_TMP" 2>/dev/null
+  fi
+fi
+
+RAW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) || RAW_BRANCH=""
+BRANCH=$(printf '%s' "${RAW_BRANCH:-}" | tr -cd 'a-zA-Z0-9._-')
 BRANCH="${BRANCH:-unknown}"
 echo "SLUG=$SLUG"
 echo "BRANCH=$BRANCH"
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# gstack-specialist-stats — compute per-specialist hit rates from review history
+# Usage: gstack-specialist-stats
+#
+# Reads all *-reviews.jsonl files across branches, parses specialist fields,
+# and outputs hit rates. Tags specialists as GATE_CANDIDATE (0 findings in 10+
+# dispatches) or NEVER_GATE (security, data-migration — insurance policy).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+PROJECT_DIR="$GSTACK_HOME/projects/$SLUG"
+
+if [ ! -d "$PROJECT_DIR" ]; then
+  echo "SPECIALIST_STATS: 0 reviews analyzed"
+  exit 0
+fi
+
+# Collect all review JSONL files (strip ---CONFIG--- and ---HEAD--- footers)
+COMBINED=""
+for f in "$PROJECT_DIR"/*-reviews.jsonl; do
+  [ -f "$f" ] || continue
+  COMBINED="$COMBINED$(sed '/^---/,$d' "$f" 2>/dev/null)
+"
+done
+
+if [ -z "$COMBINED" ]; then
+  echo "SPECIALIST_STATS: 0 reviews analyzed"
+  exit 0
+fi
+
+printf '%s' "$COMBINED" | bun -e "
+const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+const NEVER_GATE = new Set(['security', 'data-migration']);
+const stats = {};
+let reviewed = 0;
+
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (!e.specialists) continue;
+    reviewed++;
+    for (const [name, info] of Object.entries(e.specialists)) {
+      if (!stats[name]) stats[name] = { dispatched: 0, findings: 0 };
+      if (info.dispatched) {
+        stats[name].dispatched++;
+        stats[name].findings += (info.findings || 0);
+      }
+    }
+  } catch {}
+}
+
+console.log('SPECIALIST_STATS: ' + reviewed + ' reviews analyzed');
+const sorted = Object.entries(stats).sort((a, b) => a[0].localeCompare(b[0]));
+for (const [name, s] of sorted) {
+  const pct = s.dispatched > 0 ? Math.round(100 * s.findings / s.dispatched) : 0;
+  let tag = '';
+  if (NEVER_GATE.has(name)) {
+    tag = ' [NEVER_GATE]';
+  } else if (s.dispatched >= 10 && s.findings === 0) {
+    tag = ' [GATE_CANDIDATE]';
+  }
+  console.log(name + ': ' + s.dispatched + '/' + reviewed + ' dispatched, ' + s.findings + ' findings (' + pct + '%)' + tag);
+}
+" 2>/dev/null || { echo "SPECIALIST_STATS: 0 reviews analyzed"; exit 0; }
@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# gstack-team-init — generate repo-level bootstrap files for team mode
+#
+# Usage:
+#   gstack-team-init optional   # gentle CLAUDE.md suggestion, one-time offer
+#   gstack-team-init required   # CLAUDE.md enforcement + PreToolUse hook
+#
+# Run from the root of your team's repo (not from the gstack directory).
+
+set -euo pipefail
+
+MODE="${1:-}"
+
+if [ "$MODE" != "optional" ] && [ "$MODE" != "required" ]; then
+  echo "Usage: gstack-team-init {optional|required}" >&2
+  echo "" >&2
+  echo "  optional  — suggest gstack install once per developer (gentle)" >&2
+  echo "  required  — enforce gstack install, block work without it" >&2
+  exit 1
+fi
+
+# Must be in a git repo
+if ! git rev-parse --show-toplevel >/dev/null 2>&1; then
+  echo "Error: not in a git repository. Run from your project root." >&2
+  exit 1
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CLAUDE_MD="$REPO_ROOT/CLAUDE.md"
+GENERATED=()
+
+# ── Migrate vendored copy if present ──────────────────────────
+
+if [ -d "$REPO_ROOT/.claude/skills/gstack" ] && [ ! -L "$REPO_ROOT/.claude/skills/gstack" ]; then
+  if [ -f "$REPO_ROOT/.claude/skills/gstack/VERSION" ] || [ -d "$REPO_ROOT/.claude/skills/gstack/.git" ]; then
+    echo "  Found vendored gstack copy at $REPO_ROOT/.claude/skills/gstack"
+    echo "  Team mode uses the global install — removing vendored copy..."
+    ( cd "$REPO_ROOT" && git rm -r --cached .claude/skills/gstack/ 2>/dev/null ) || true
+    if [ -f "$REPO_ROOT/.gitignore" ]; then
+      if ! grep -qF '.claude/skills/gstack/' "$REPO_ROOT/.gitignore" 2>/dev/null; then
+        echo '.claude/skills/gstack/' >> "$REPO_ROOT/.gitignore"
+      fi
+    else
+      echo '.claude/skills/gstack/' > "$REPO_ROOT/.gitignore"
+    fi
+    rm -rf "$REPO_ROOT/.claude/skills/gstack"
+    GENERATED+=(".gitignore")
+    echo "  Removed vendored copy and added .claude/skills/gstack/ to .gitignore"
+  fi
+fi
+
+# ── CLAUDE.md snippet ──────────────────────────────────────────
+
+if [ "$MODE" = "optional" ]; then
+  SNIPPET='## gstack (recommended)
+
+This project uses [gstack](https://github.com/garrytan/gstack) for AI-assisted workflows.
+Install it for the best experience:
+
+```bash
+git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+cd ~/.claude/skills/gstack && ./setup --team
+```
+
+Skills like /qa, /ship, /review, /investigate, and /browse become available after install.
+Use /browse for all web browsing. Use ~/.claude/skills/gstack/... for gstack file paths.'
+else
+  SNIPPET='## gstack (REQUIRED — global install)
+
+**Before doing ANY work, verify gstack is installed:**
+
+```bash
+test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING"
+```
+
+If GSTACK_MISSING: STOP. Do not proceed. Tell the user:
+
+> gstack is required for all AI-assisted work in this repo.
+> Install it:
+> ```bash
+> git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+> cd ~/.claude/skills/gstack && ./setup --team
+> ```
+> Then restart your AI coding tool.
+
+Do not skip skills, ignore gstack errors, or work around missing gstack.
+
+Using gstack skills: After install, skills like /qa, /ship, /review, /investigate,
+and /browse are available. Use /browse for all web browsing.
+Use ~/.claude/skills/gstack/... for gstack file paths (the global path).'
+fi
+
+# Check if CLAUDE.md already has a gstack section
+if [ -f "$CLAUDE_MD" ] && grep -q "## gstack" "$CLAUDE_MD" 2>/dev/null; then
+  echo "CLAUDE.md already has a gstack section. Skipping CLAUDE.md update."
+  echo "  To replace it, remove the existing ## gstack section and re-run."
+else
+  if [ -f "$CLAUDE_MD" ]; then
+    echo "" >> "$CLAUDE_MD"
+  fi
+  echo "$SNIPPET" >> "$CLAUDE_MD"
+  GENERATED+=("CLAUDE.md")
+  echo "  + CLAUDE.md — added gstack $MODE section"
+fi
+
+# ── Required mode: enforcement hook ────────────────────────────
+
+if [ "$MODE" = "required" ]; then
+  HOOKS_DIR="$REPO_ROOT/.claude/hooks"
+  SETTINGS="$REPO_ROOT/.claude/settings.json"
+
+  # Create enforcement hook script
+  mkdir -p "$HOOKS_DIR"
+  cat > "$HOOKS_DIR/check-gstack.sh" << 'HOOK_EOF'
+#!/bin/bash
+# Block skill usage when gstack is not installed globally.
+
+if [ ! -d "$HOME/.claude/skills/gstack/bin" ]; then
+  cat >&2 <<'MSG'
+BLOCKED: gstack is not installed globally.
+
+gstack is required for AI-assisted work in this repo.
+
+Install it:
+  git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
+  cd ~/.claude/skills/gstack && ./setup --team
+
+Then restart your AI coding tool.
+MSG
+  echo '{"permissionDecision":"deny","message":"gstack is required but not installed. See stderr for install instructions."}'
+  exit 0
+fi
+
+echo '{}'
+HOOK_EOF
+  chmod +x "$HOOKS_DIR/check-gstack.sh"
+  GENERATED+=(".claude/hooks/check-gstack.sh")
+  echo "  + .claude/hooks/check-gstack.sh — enforcement hook"
+
+  # Add hook to project-level settings.json
+  if command -v bun >/dev/null 2>&1; then
+    bun -e "
+      const fs = require('fs');
+      const settingsPath = '$SETTINGS';
+
+      let settings = {};
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+
+      if (!settings.hooks) settings.hooks = {};
+      if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+      // Dedup
+      const exists = settings.hooks.PreToolUse.some(entry =>
+        entry.matcher === 'Skill' &&
+        entry.hooks && entry.hooks.some(h => h.command && h.command.includes('check-gstack'))
+      );
+
+      if (!exists) {
+        settings.hooks.PreToolUse.push({
+          matcher: 'Skill',
+          hooks: [{
+            type: 'command',
+            command: '\"\$CLAUDE_PROJECT_DIR/.claude/hooks/check-gstack.sh\"'
+          }]
+        });
+      }
+
+      const tmp = settingsPath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      fs.renameSync(tmp, settingsPath);
+    " 2>/dev/null
+    GENERATED+=(".claude/settings.json")
+    echo "  + .claude/settings.json — PreToolUse hook registered"
+  else
+    echo "  ! bun not found — manually add the PreToolUse hook to .claude/settings.json"
+  fi
+fi
+
+# ── Summary ────────────────────────────────────────────────────
+
+echo ""
+echo "Team mode ($MODE) initialized."
+echo ""
+if [ ${#GENERATED[@]} -gt 0 ]; then
+  echo "Commit the generated files:"
+  echo "  git add ${GENERATED[*]}"
+  echo "  git commit -m \"chore: require gstack for AI-assisted work\""
+fi
+echo ""
+echo "Each developer then runs:"
+echo "  git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack"
+echo "  cd ~/.claude/skills/gstack && ./setup --team"
@@ -117,6 +117,11 @@ case "$HTTP_CODE" in
    # Advance by SENT count (not inserted count) because we can't map inserted back to
    # source lines. If inserted==0, something is systemically wrong — don't advance.
    INSERTED="$(grep -o '"inserted":[0-9]*' "$RESP_FILE" 2>/dev/null | grep -o '[0-9]*' || echo "0")"
+    # Check for upsert errors (installation tracking failures) — log but don't block cursor advance
+    UPSERT_ERRORS="$(grep -o '"upsertErrors"' "$RESP_FILE" 2>/dev/null || true)"
+    if [ -n "$UPSERT_ERRORS" ]; then
+      echo "[gstack-telemetry-sync] Warning: installation upsert errors in response" >&2
+    fi
    if [ "${INSERTED:-0}" -gt 0 ] 2>/dev/null; then
      NEW_CURSOR=$(( CURSOR + COUNT ))
      echo "$NEW_CURSOR" > "$CURSOR_FILE" 2>/dev/null || true
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# gstack-timeline-log — append a timeline event to the project timeline
+# Usage: gstack-timeline-log '{"skill":"review","event":"started","branch":"main"}'
+#
+# Session timeline: local-only, never sent anywhere.
+# Required fields: skill, event (started|completed).
+# Optional: branch, outcome, duration_s, session, ts.
+# Validation failure → skip silently (non-blocking).
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+mkdir -p "$GSTACK_HOME/projects/$SLUG"
+
+INPUT="$1"
+
+# Validate: input must be parseable JSON with required fields
+if ! printf '%s' "$INPUT" | bun -e "
+  const j = JSON.parse(await Bun.stdin.text());
+  if (!j.skill || !j.event) process.exit(1);
+" 2>/dev/null; then
+  exit 0  # skip silently, non-blocking
+fi
+
+# Inject timestamp if not present
+if ! printf '%s' "$INPUT" | bun -e "const j=JSON.parse(await Bun.stdin.text()); if(!j.ts) process.exit(1)" 2>/dev/null; then
+  INPUT=$(printf '%s' "$INPUT" | bun -e "
+    const j = JSON.parse(await Bun.stdin.text());
+    j.ts = new Date().toISOString();
+    console.log(JSON.stringify(j));
+  " 2>/dev/null) || true
+fi
+
+echo "$INPUT" >> "$GSTACK_HOME/projects/$SLUG/timeline.jsonl"
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# gstack-timeline-read — read and format project timeline
+# Usage: gstack-timeline-read [--since "7 days ago"] [--limit N] [--branch NAME]
+#
+# Session timeline: local-only, never sent anywhere.
+# Reads ~/.gstack/projects/$SLUG/timeline.jsonl, filters, formats.
+# Exit 0 silently if no timeline file exists.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+eval "$("$SCRIPT_DIR/gstack-slug" 2>/dev/null)"
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+
+SINCE=""
+LIMIT=20
+BRANCH=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since) SINCE="$2"; shift 2 ;;
+    --limit) LIMIT="$2"; shift 2 ;;
+    --branch) BRANCH="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+TIMELINE_FILE="$GSTACK_HOME/projects/$SLUG/timeline.jsonl"
+
+if [ ! -f "$TIMELINE_FILE" ]; then
+  exit 0
+fi
+
+cat "$TIMELINE_FILE" 2>/dev/null | bun -e "
+const lines = (await Bun.stdin.text()).trim().split('\n').filter(Boolean);
+const since = '${SINCE}';
+const branch = '${BRANCH}';
+const limit = ${LIMIT};
+
+let sinceMs = 0;
+if (since) {
+  // Parse relative time like '7 days ago'
+  const match = since.match(/(\d+)\s*(day|hour|minute|week|month)s?\s*ago/i);
+  if (match) {
+    const n = parseInt(match[1]);
+    const unit = match[2].toLowerCase();
+    const ms = { minute: 60000, hour: 3600000, day: 86400000, week: 604800000, month: 2592000000 };
+    sinceMs = Date.now() - n * (ms[unit] || 86400000);
+  }
+}
+
+const entries = [];
+for (const line of lines) {
+  try {
+    const e = JSON.parse(line);
+    if (sinceMs && new Date(e.ts).getTime() < sinceMs) continue;
+    if (branch && e.branch !== branch) continue;
+    entries.push(e);
+  } catch {}
+}
+
+if (entries.length === 0) process.exit(0);
+
+// Take last N entries
+const recent = entries.slice(-limit);
+
+// Skill counts (completed events only)
+const counts = {};
+const branches = new Set();
+for (const e of entries) {
+  if (e.event === 'completed') {
+    counts[e.skill] = (counts[e.skill] || 0) + 1;
+  }
+  if (e.branch) branches.add(e.branch);
+}
+
+// Output summary
+const countStr = Object.entries(counts)
+  .sort((a, b) => b[1] - a[1])
+  .map(([s, n]) => n + ' /' + s)
+  .join(', ');
+
+if (countStr) {
+  console.log('TIMELINE: ' + countStr + ' across ' + branches.size + ' branch' + (branches.size !== 1 ? 'es' : ''));
+}
+
+// Output recent events
+console.log('');
+console.log('## Recent Events');
+for (const e of recent) {
+  const ts = (e.ts || '').replace('T', ' ').replace(/\.\d+Z$/, 'Z');
+  const dur = e.duration_s ? ' (' + e.duration_s + 's)' : '';
+  const outcome = e.outcome ? ' [' + e.outcome + ']' : '';
+  console.log('- ' + ts + ' /' + e.skill + ' ' + e.event + outcome + dur + (e.branch ? ' on ' + e.branch : ''));
+}
+" 2>/dev/null || exit 0
@@ -227,6 +227,13 @@ if [ -n "$_GIT_ROOT" ]; then
  fi
 fi

+# ─── Remove SessionStart hook from Claude Code settings ─────
+SETTINGS_HOOK="$(dirname "$0")/gstack-settings-hook"
+SESSION_UPDATE="$(dirname "$0")/gstack-session-update"
+if [ -x "$SETTINGS_HOOK" ]; then
+  "$SETTINGS_HOOK" remove "$SESSION_UPDATE" 2>/dev/null && REMOVED+=("SessionStart hook") || true
+fi
+
 # ─── Remove global state ────────────────────────────────────
 if [ "$KEEP_STATE" -eq 0 ] && [ -d "$STATE_DIR" ]; then
  rm -rf "$STATE_DIR"