Scope Cache Refresh Changes Safely

When changing cache-refresh behavior for API routes:

Prefer editing server/src/honoMiddlewares/refreshCacheConfigs.ts to add or remove route entries.
Do not remove or bypass logic in server/src/honoMiddlewares/refreshCacheMiddleware.ts unless the user explicitly asks to change middleware behavior globally.
If the request is ambiguous, ask whether they want a route-level config change or a global middleware behavior change.

Cache Version Increment Policy

Treat cache_version as a DB-side stale-sync guard for syncItemV4, not a general cache mutation counter.

Increment cache_version only when needed

Increment only for DB updates that must not be overwritten by stale sync payloads read from cache (for example lifecycle or billing transitions).

Do not increment on cache-side/runtime patch paths

For runtime balance/reset/cache patch flows, do not bump cache_version in cache writers or Lua update scripts.

Examples:

FullSubject cache patch helpers (updateSubjectBalanceCache, reset/deduction cache patch sync helpers)
FullSubject Lua cache update scripts (updateSubjectBalances)
Update-balance runtime paths that patch Redis and then sync

Call-site rule for CusEntService.update

When using CusEntService.update(...) in runtime FullSubject cache patch flows, set incrementCacheVersion explicitly.

Use incrementCacheVersion: false for routine balance/reset/adjustment updates that are mirrored to Redis.
Use incrementCacheVersion: true only for intentional DB-side stale-write protection transitions.

Why

Incorrect version bumps create CACHE_VERSION_MISMATCH conflicts in syncItemV4, causing repeated invalidation and stale/lost update behavior.

Legacy exception (review-required)

There is a legacy-compatibility exception in the adjust-balance flow:

adjustBalanceDbAndCache currently uses CusEntService.increment/decrement, which increments cache_version.
Treat this as a reviewable legacy action, not a pattern to copy into new runtime/cache patch paths.
Any new or refactored runtime balance/reset/cache patch code should continue following this policy and avoid adding new cache-version bumps by default.

Project Context System

Projects maintain state in .context/<project>/ folders across sessions. Tasks are optional parallel workstreams within a project.

Reading context (session start)

When the user mentions a project or task name and .context/<name>/ exists:

Read project STATUS.md first (20-30 line "resume card")
If the project has tasks/, list active tasks
If the user mentions a specific task, read tasks/<task>/STATUS.md
Read the most recent session summary if more detail is needed
Do NOT read everything upfront. Use progressive disclosure.

Updating context (at breakpoints, NOT continuously)

Update at these moments ONLY:

Phase or milestone completed
Architectural decision made (append to DECISIONS.md)
User says they're done or switching tasks
Blocker discovered or resolved
Task created, completed, or handed off

Do NOT update context during normal coding work. Work first, compact at breakpoints.

Compaction quality

STATUS.md must be:

Correct (reflects actual current state, not stale)
Complete (no critical information missing)
Concise (project < 30 lines, task < 20 lines)

Always REWRITE STATUS.md completely rather than append.

File structure

.context/<project>/
  STATUS.md       -- project resume card (includes Active Tasks section)
  PLAN.md         -- phases and architecture
  DECISIONS.md    -- append-only decision log
  sessions/       -- dated session summaries
  tasks/          -- optional parallel workstreams
    <task>/
      STATUS.md   -- task resume card
      DECISIONS.md

Task handoff

When a task is being handed to another agent, ensure the task's STATUS.md is up to date -- it's the handoff artifact.

3.9 KiB Raw Blame History