Let install.sh delete, and teach doctor to look the other way

install.sh has never been able to remove a key. The comment above the merge said
retired keys were del()ed explicitly below; no such code was ever written. So
every key this repo shipped and later dropped stayed in the live settings file
forever. It bit twice, and both times the fix was a hand edit on one machine,
which fixes nothing for anybody else. There is now a RETIRED list the merge
delpaths, and the merge is proven against a planted sandbox key: it goes, while
forceLoginMethod and remote.defaultEnvironmentId survive.

Superset is gone with it. That notifier was stapled to five hook events of every
install, including two events that existed only to feed it, and it is a tool
this setup no longer uses. A stranger installing vstack should not inherit hooks
for someone else's software. Check 11 asserts it stays gone rather than trusting
the next reader to notice.

doctor --drift only ever walked repo to machine, so it could see a file that had
vanished and never a file that should not be there. That is how orchestrate.md
outlived its own deletion, and how a pre-vstack bootstrap script sat in
~/.claude/scripts propping up a command that was broken for everyone else. It
now reads settings.json keys back and classifies extras, and lists files under
~/.claude that the repo does not ship.

Files split by git history rather than by guess: one the repo used to ship is a
delete that never landed, one it never had is yours and not doctor's business.
Two wrong answers on the way there, both instructive. rev-list --objects takes a
pathspec but walks every reachable object, so it answers yes for paths that
never existed. And `git log | grep -q` under pipefail returns 141 on a match,
because grep exits first and git takes SIGPIPE — which inverted the test and
filed every leftover as a user file.

verify.sh 22/22, gate-falsifiability.sh 23/23, doctor --drift clean.

Author: itsvedantkumar

.claude/verify.sh

@@ -171,7 +171,8 @@ if command -v jq >/dev/null; then
     # otherwise clobber each other's scratch files mid-check.
     md=$(mktemp -d)
     out=$(printf '{}\n' > "$md/a.json"; cp claude/settings.json "$md/b.json";
-          jq -s --arg h "/tmp/hooks" --arg n "true" "$prog" "$md/a.json" "$md/b.json" 2>&1)
+          jq -s --arg h "/tmp/hooks" --argjson retired '["probe_retired_key"]' \
+             "$prog" "$md/a.json" "$md/b.json" 2>&1)
     if printf '%s' "$out" | jq -e . >/dev/null 2>&1; then
       ok "settings merge program"
     else
@@ -266,12 +267,20 @@ if command -v jq >/dev/null; then
   if [ -z "$prog" ]; then
     errs="$errs\ncould not extract the hook rebuild program from install.sh"
   else
-    for ev in SessionStart UserPromptSubmit PostToolUse Stop PostToolUseFailure SessionEnd PermissionRequest; do
+    for ev in SessionStart UserPromptSubmit PostToolUse Stop PostToolUseFailure; do
       printf '%s' "$prog" | grep -qE "^ *$ev: *\[" || errs="$errs\n$ev: missing from install.sh hook rebuild"
     done
-    # The notify hook is what reaches the phone. It is wired to five of the seven events.
-    nn=$(printf '%s' "$prog" | grep -cF 'command:$n')
-    [ "$nn" -eq 5 ] || errs="$errs\nnotify wired to $nn sites in install.sh, expected 5"
+    # The user lane wires the same five events as the project lane and nothing more. It used to
+    # wire seven, because SessionEnd and PermissionRequest existed only to reach a third-party
+    # notifier (Superset) that this setup no longer uses. Installing vstack should not staple a
+    # foreign tool's script to five hook events on a stranger's machine, so the notifier is gone
+    # and this asserts it stays gone rather than trusting the next reader to notice.
+    for dead in SessionEnd PermissionRequest; do
+      printf '%s' "$prog" | grep -qE "^ *$dead: *\[" \
+        && errs="$errs\n$dead: back in the install.sh hook rebuild — it exists only to serve a notifier this setup dropped"
+    done
+    grep -qi 'superset' install.sh \
+      && errs="$errs\ninstall.sh still references the retired Superset notifier"
   fi
 
   # Lane 3 — plugin marketplace. Deliberately narrow, and asserted as an exact set rather than

bin/doctor

@@ -106,6 +106,109 @@ if [ "${1:-}" = "--drift" ]; then
   [ -f "$REPO/shell/claude-parity.zsh" ] && \
     check_item "shell/claude-parity.zsh" "$REPO/shell/claude-parity.zsh" "$HOME/.config/agents/shell/claude-parity.zsh"
 
+  # --- settings.json keys -------------------------------------------------------------------
+  # The two blind spots below are why this whole section exists. --drift compared files it
+  # could diff byte-for-byte and quietly skipped the two surfaces that cannot be compared that
+  # way, so both rotted for months while it printed "no drift".
+  #
+  # First: ~/.claude/settings.json is a MERGE, never a copy, so it can never be diffed against
+  # the repo. install.sh had no way to delete, which meant every key vstack ever shipped and
+  # later dropped stayed in the live file forever. It happened twice. install.sh owns deletion
+  # now (see RETIRED there), but that only strips keys someone remembered to list, so this
+  # reads the live file back and names anything the repo does not ship.
+  #
+  # USER_SCOPE keys legitimately exist only on a machine: they are per-account or per-device
+  # and have no business in a public repo. Anything outside both sets is unclassified — not
+  # necessarily wrong, but nobody has decided what it is, which is exactly the state the dead
+  # skillOverrides and sandbox blocks sat in.
+  if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude/settings.json" ]; then
+    USER_SCOPE='["forceLoginMethod","remote","enabledPlugins","extraKnownMarketplaces","preferredNotifChannel","permissions","skipDangerousModePermissionPrompt","statusLine","hooks","feedbackSurveyState","hasCompletedOnboarding","lastOnboardingVersion","userID","oauthAccount","customApiKeyResponses","tipsHistory","promptQueueUseCount","installMethod","autoUpdates","theme"]'
+    extra=$(jq -r --slurpfile repo "$REPO/claude/settings.json" --argjson us "$USER_SCOPE" '
+      ($repo[0] | keys) as $shipped
+      | keys - $shipped - $us
+      | .[]' "$HOME/.claude/settings.json" 2>/dev/null)
+    if [ -n "$extra" ]; then
+      echo "unclassified settings.json key(s) not shipped by the repo and not user-scope:"
+      printf '          %s\n' $extra
+      echo "          decide each one: add it to claude/settings.json, to RETIRED in install.sh, or to USER_SCOPE here"
+      DRIFT=1
+    fi
+  fi
+
+  # --- files the repo never shipped -----------------------------------------------------------
+  # Second blind spot: --drift only ever walked repo -> machine, so it could see a file that
+  # went missing and never a file that should not be there. A deleted orchestrate.md survived
+  # in ~/.claude for months that way, and a pre-vstack bootstrap-claude-project.sh sat in
+  # ~/.claude/scripts propping up a command that was broken for everyone else on earth.
+  #
+  # Reports only; never deletes. These are the user's files, and a health check that removes
+  # things you did not ask it to remove is worse than the drift.
+  #
+  # Symlinks are skipped on purpose: plugin- and Claude-Code-bundled skills (skill-creator,
+  # pdf, docx, pptx, xlsx) link in from elsewhere and are expected.
+  RUNTIME_TOP='projects sessions session-env shell-snapshots tasks todos plans telemetry plugins cache chrome daemon downloads paste-cache jobs ide statsig backups scheduled-tasks history.jsonl stats-cache.json mcp-needs-auth-cache.json settings.json settings.local.json .credentials.json .last-update-result.json .last-cleanup .cc-writes CLAUDE.md statusline.sh hooks agents commands skills'
+  stale=""
+  for p in "$HOME"/.claude/* "$HOME"/.claude/.[!.]*; do
+    [ -e "$p" ] || continue
+    b=$(basename "$p")
+    case " $RUNTIME_TOP " in *" $b "*) continue ;; esac
+    stale="$stale $b"
+  done
+  for kind in hooks:'*.sh' agents:'*.md' commands:'*.md'; do
+    d=${kind%%:*}; pat=${kind#*:}
+    for p in "$HOME"/.claude/"$d"/$pat; do
+      [ -e "$p" ] || continue
+      [ -L "$p" ] && continue
+      b=$(basename "$p")
+      [ -e "$REPO/claude/$d/$b" ] || stale="$stale $d/$b"
+    done
+  done
+  for p in "$HOME"/.claude/skills/*/; do
+    [ -d "$p" ] || continue
+    s=$(basename "$p")
+    [ -L "${p%/}" ] && continue
+    [ -d "$REPO/claude/skills/$s" ] || stale="$stale skills/$s"
+  done
+  # Two very different things end up in that list, and calling both "drift" would be wrong.
+  # A file the repo USED to ship and later deleted is a genuine leftover: the deletion never
+  # reached this machine, which is precisely how orchestrate.md outlived its removal. A file
+  # the repo has never had at any commit is the user's own, and a health check has no standing
+  # to call that an error. Git history is what separates them, so ask it instead of guessing.
+  if [ -n "$stale" ]; then
+    leftover=""; theirs=""
+    for b in $stale; do
+      case "$b" in
+        hooks/*|agents/*|commands/*|skills/*) rel="claude/$b" ;;
+        *)                                    rel="claude/$b" ;;
+      esac
+      # Two traps here, both of which produced a confidently wrong answer:
+      #
+      # `git log`, not `rev-list --objects`. The latter accepts a pathspec but still walks every
+      # reachable object, so it says "yes" for a path that has never existed and files all of
+      # the user's own files under "the repo dropped this".
+      #
+      # And capture the output rather than piping into `grep -q`. Under `set -o pipefail` grep
+      # exits the moment it matches, git takes SIGPIPE, and the pipeline reports 141 — on a
+      # match. Piping inverted the test: every leftover was classified as the user's own file.
+      hist=$(git -C "$REPO" log --all --oneline -- "$rel" 2>/dev/null)
+      if [ -n "$hist" ]; then
+        leftover="$leftover $b"
+      else
+        theirs="$theirs $b"
+      fi
+    done
+    if [ -n "$leftover" ]; then
+      echo "left over from a version this repo used to ship (the delete never reached this machine):"
+      printf '          %s\n' $leftover
+      echo "          safe to remove — git history shows the repo dropped them"
+      DRIFT=1
+    fi
+    if [ -n "$theirs" ]; then
+      echo "note: in ~/.claude but never shipped by this repo, so presumed yours:"
+      printf '          %s\n' $theirs
+    fi
+  fi
+
   # Behind-remote is informational only — never fail solely for being behind.
   if git -C "$REPO" rev-parse --symbolic-full-name '@{u}' >/dev/null 2>&1; then
     git -C "$REPO" fetch -q 2>/dev/null || true

install.sh

@@ -165,11 +165,17 @@ fi
 # paths (user scope has no $CLAUDE_PROJECT_DIR). The portable file is authoritative for
 # every key it ships — including enabledPlugins and skillOverrides, which is replaced
 # wholesale so overrides for deleted skills don't linger in the live file forever. Keys the
-# portable file never mentions (forceLoginMethod / remote / permissions) survive untouched;
-# retired top-level keys are del()ed explicitly below.
+# portable file never mentions (forceLoginMethod / remote / permissions) survive untouched.
+#
+# RETIRED is the part that used to be a lie. The comment here claimed retired keys were
+# del()ed "explicitly below" and no such code was ever written, so every key this repo has
+# ever shipped and later dropped stayed in the live file forever. It bit twice — a dead
+# skillOverrides block, then a sandbox block — and both times the fix was a manual edit on
+# one machine, which fixes nothing for anyone else. A merge that cannot delete is not a
+# merge, it is an accumulator. Add a key here when you remove it from claude/settings.json.
+RETIRED='["sandbox","skillOverridesLegacy","enabledMcpjsonServers","autoCompactEnabled"]'
 US="$HOME/.claude/settings.json"; back "$US"
 [ -f "$US" ] || { [ "$DRY" = 0 ] && echo '{}' > "$US"; }
-NOTIFY='[ -n "$SUPERSET_HOME_DIR" ] && [ -x "$SUPERSET_HOME_DIR/hooks/notify.sh" ] && SUPERSET_AGENT_ID=claude "$SUPERSET_HOME_DIR/hooks/notify.sh" || true'
 if [ "$DRY" = 0 ] && [ "$HAVE_JQ" = 0 ]; then
   # No jq: never hand-merge JSON. Write the portable settings only when there is nothing
   # to lose, otherwise leave the existing file untouched.
@@ -181,27 +187,23 @@ if [ "$DRY" = 0 ] && [ "$HAVE_JQ" = 0 ]; then
   fi
 elif [ "$DRY" = 0 ]; then
   tmp=$(mktemp)
-  jq -s --arg h "$HOME/.claude/hooks" --arg n "$NOTIFY" '
+  jq -s --arg h "$HOME/.claude/hooks" --argjson retired "$RETIRED" '
     ((.[1] | del(.hooks)) as $portable
       | (.[0] * $portable)
-      | .skillOverrides = ($portable.skillOverrides // {}))
+      | .skillOverrides = ($portable.skillOverrides // {})
+      | delpaths([$retired[] | [.]]))
     | .hooks = {
         SessionStart: [
-          { hooks: [ {type:"command", command:($h+"/inject-session-context.sh"), statusMessage:"context"} ] },
-          { hooks: [ {type:"command", command:$n} ] } ],
+          { hooks: [ {type:"command", command:($h+"/inject-session-context.sh"), statusMessage:"context"} ] } ],
         UserPromptSubmit: [
           { hooks: [ {type:"command", command:($h+"/inject-session-context.sh")} ] } ],
         PostToolUse: [
           { matcher:"Edit|Write|MultiEdit",
             hooks: [ {type:"command", command:($h+"/format.sh"), statusMessage:"format"} ] } ],
         Stop: [
-          { hooks: [ {type:"command", command:($h+"/verify-gate.sh")} ] },
-          { hooks: [ {type:"command", command:$n} ] } ],
+          { hooks: [ {type:"command", command:($h+"/verify-gate.sh")} ] } ],
         PostToolUseFailure: [
-          { matcher:"*", hooks: [ {type:"command", command:($h+"/failure-diagnose.sh")} ] },
-          { matcher:"*", hooks: [ {type:"command", command:$n} ] } ],
-        SessionEnd:        [ { hooks: [ {type:"command", command:$n} ] } ],
-        PermissionRequest: [ { matcher:"*", hooks: [ {type:"command", command:$n} ] } ]
+          { matcher:"*", hooks: [ {type:"command", command:($h+"/failure-diagnose.sh")} ] } ]
       }
     | .statusLine = {type:"command", command:(($h|rtrimstr("/hooks")) + "/statusline.sh"), padding:0, refreshInterval:3}
   ' "$US" "$SRC/claude/settings.json" > "$tmp"

secrets.env.example

@@ -10,12 +10,7 @@
 export CLOUDFLARE_API_TOKEN=
 export CLOUDFLARE_ACCOUNT_ID=
 
-# --- Transactional email ---
-
 # --- Anthropic SDK key, for APPS you build ---
 # Deliberately NOT named ANTHROPIC_API_KEY: that name makes Claude Code bill API credits
 # instead of your subscription. The shell wrapper strips it, doctor checks it stays unset.
 export ANTHROPIC_SDK_API_KEY=
-
-# --- Optional: Superset notifier (hooks post events here when set) ---
-export SUPERSET_HOME_DIR=