User Story

As an ApexStack fork maintainer, I want Claude Code to show me on session start how many commits behind upstream me2resh/apexstack my fork is, so I know when to run /update without having to remember to check manually.

Why

Session from 2026-04-17: the ops fork was 10 commits behind upstream and the maintainer only discovered this because a hook misfired on a stale version (the --repo fix in #54 hadn't flowed down). Silent drift is the single biggest weakness of the fork-based distribution model — documented in the ops-fork PRD-0002 as problem #1 of four.

With /update shipping in #58, the next missing piece is "tell me when to run it."

Acceptance Criteria

• New shell hook at .claude/hooks/check-upstream-drift.sh runs on SessionStart

• Hook is silent if:

  • upstream remote is missing (fresh clone, first-time user)
  • Network fetch fails (offline / git hosting down)
  • Fork is up-to-date

• Hook prints a one-line banner to stderr if behind:

  ApexStack: <N> commits behind upstream/<default-branch>. Run /update to sync.
  

• Hook caches the last-fetched time in .claude/session/last-upstream-fetch and skips the network call if run within the last 10 minutes (cheap session-start cost, avoids hammering origin for frequent restarts)

• Wired in .claude/settings.json on the SessionStart matcher

• Documented in docs/multi-project.md § "Upgrades" near the /update reference

Out of Scope

• Tagged-release dimension (apexstack doesn't have tags yet — see PRD-0002 change feat(#100): animated /idea shell demo in the hero #5)
• Non-default-branch awareness (only compare against main / master)
• Multi-remote check (just upstream)
• Auto-running /update (banner only, always user-initiated)

Design Notes

This is change #2 in PRD-0002 (fork distribution model). Compounds with #58 (/update skill): banner tells you when to sync, skill does the sync. Shipping them together is the first meaningful UX improvement for external fork users.

The hook should be as lightweight as possible — it runs on every session start, so no gh calls, no heavy git operations, just git rev-list --count main..upstream/main after an optional git fetch upstream --quiet. Fetch is the only network I/O; cache controls frequency.