# 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//` folders across sessions. Tasks are optional parallel workstreams within a project. ### Default: NOT interacting with a project **Unless the user explicitly mentions a project or task by name, assume the current conversation is NOT associated with any project.** Session-start hooks may surface a list of active projects as reference material — that alone is NOT a signal that the current work belongs to any of them. Do not: - Read `.context/**` files proactively - Write, update, or append to any project's STATUS.md / DECISIONS.md / sessions - Assume a script, audit, or change is part of a project just because it touches files related to one (e.g. a user-of-framework script is not part of the framework's project) Only engage with `.context//` when the user explicitly references the project, opens a task in it, or asks for project-tracking actions. ### Reading context (when a project IS referenced) When the user mentions a project or task name and `.context//` exists: 1. Read project STATUS.md first (20-30 line "resume card") 2. If the project has `tasks/`, list active tasks 3. If the user mentions a specific task, read `tasks//STATUS.md` 4. Read the most recent session summary if more detail is needed 5. Do NOT read everything upfront. Use progressive disclosure. ### Updating context (at breakpoints, NOT continuously) Only update when the current work IS part of a project (see default-off rule above). When it is, 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. <<<<<<< HEAD A STATUS.md entry should record changes to the project itself -- not one-off work that merely uses the project (e.g. writing a consumer script of a framework is not a framework-project update). ======= A STATUS.md entry should record changes to the project itself — not one-off work that merely uses the project (e.g. writing a consumer script of a framework is not a framework-project update). >>>>>>> a62195ba706f12fbd35f7ecf48b4701011115101 ### 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// 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 / 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.