Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (72 loc) · 4.99 KB

AGENTS.md

File metadata and controls

104 lines (72 loc) · 4.99 KB

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.

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/<project>/ 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/<name>/ 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/<task>/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.

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).

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.