Classify JobKinds: user-facing vs server-internal

[Sootopolis]

Question

Which JobKinds deserve to be in the user-facing CLI / HTTP surface, and which are pure server-internal bookkeeping that users shouldn't have to think about?

Proposal

Kind	User cares?	Today	Proposed
Recruitment	yes — primary feature	user-facing	user-facing
Membership	yes — admin tool	user-facing	user-facing
Stats	yes — performance reports	user-facing	user-facing
History	mixed — "ingest matches" is a real op, but most fires are prep	user-facing	user-facing
Blacklist	yes — recruitment input	user-facing	user-facing
MatchRef	no — pure rename-recovery bookkeeping	user-facing	server-internal
ClubData	no/indirect — feeds authz + scouting	partly exposed	server-internal

Implications if accepted

• No public CLI subcommand for internal kinds. Drop ccas ref and ccas clubdata from the public command table (decline subcommands issue).

• No public HTTP route under /api/jobs/* for internal kinds. Either drop POST /api/jobs/clubdata entirely (clubdata-route issue pivots) or move to POST /api/admin/jobs/clubdata if an admin namespace exists.

• Server auto-creates default JobSchedule rows at first boot:

  • MatchRef — daily, e.g. 03:00.
  • ClubData — every 6h.

• Optional hidden escape hatches via decline Visibility.Partial:

  • ccas admin ref --force
  • ccas admin clubdata --force <slug>

  Useful for ops debugging ("I just got promoted to admin and want CCAS to notice now"). Not advertised in --help.

• Operator can still edit/disable the auto-schedules via ccas schedule.

Why this matters

Asking a user to run ccas ref is asking them to compensate for Chess.com's behaviour (handle renames). That's CCAS implementation detail leaking into UX. Same for ccas clubdata: users consume the data indirectly through recruitment / authz; they shouldn't have to remember to refresh it.

Counter-arguments worth considering

• Force-refresh is sometimes legitimate. Just-promoted admin wants CCAS to recognise them. The hidden ccas admin subcommand handles this.
• Debugging. Internal kinds should still be triggerable manually during development. Same hidden subcommand handles this.
• Future automation. If a downstream feature ever needs to chain "refresh club data, then run recruitment," it should do so via internal API, not by simulating CLI commands. Internal-only is consistent with that.

Affects

• CLI subcommand tree via decline #46 — CLI subcommand tree via decline (public subcommand scope).
• Bootstrap default JobSchedule rows for server-internal kinds at first boot #45 — POST /api/jobs/clubdata route (route scope, possible pivot).

Decision needed

Accept the table as proposed? Modifications? Once decided, close this issue with a comment recording the chosen classification, then unblock the two affected issues (#45 and #46 — remove their pending-decision label).

Reference

Tracked under epic #40 (CLI v0). Roadmap: ~/.claude/plans/ultra-sparkling-unicorn.md (to be amended once this decision lands).

[Sootopolis]

Decision (2026-05-27): accept the proposed table.

Kind	Class	Default JobSchedule
Recruitment	user-facing	—
Membership	user-facing	—
History	user-facing	daily, all clubs (cheap mode — see #62)
Stats	user-facing	—
MatchRef	server-internal	daily 03:00 UTC
ClubData	server-internal	every 6h

Note on History: stays user-facing because both Stats and Recruitment depend on history-populated tables (ClubMatch, ClubMatchBoard). Verified Recruitment's discoverMatchBoardOpponents strategy and PlayerMatchRef.findOrInfer rename-recovery both read history tables; Recruitment degrades gracefully without history, Stats does not. Default daily JobSchedule for History keeps steady state fresh so scheduled Stats/Recruitment runs don't surprise users with empty results. #62 carves out a fast-path History mode (Registered + InProgress only) as the natural cadence companion for the daily schedule.

Cascading actions:

• #45 pivots: drop the public POST /api/jobs/clubdata route; replaced by server-side default-schedule bootstrap for MatchRef + ClubData + History at first boot.
• #46 subcommand table: remove public ccas ref / ccas clubdata; add hidden ccas admin {ref|clubdata} --force under decline Visibility.Partial. pending-decision label removed.
• Default JobSchedule rows seeded at first boot (target: ServerTables.ensureTables in src/main/scala/ccas/server/ServerTables.scala).

Closing.