REQ-O-018: --no-cache and --cache-ttl Flags

Tier: Opt-In | Priority: P3

Source: §30 Undeclared Filesystem Side Effects

Addresses: Severity: Medium / Token Spend: Low / Time: Low / Context: Low

Description

For commands that write to caches, the framework MUST provide --no-cache (skip cache reads and writes for this invocation) and --cache-ttl <seconds> (override the default cache TTL). These flags MUST be automatically available on commands that declare a cache entry in filesystem_side_effects (REQ-C-011). With --no-cache, the command MUST NOT read from or write to any declared cache path.

Acceptance Criteria

--no-cache causes the command to bypass all declared cache files
--cache-ttl 0 is equivalent to --no-cache
Cache files older than --cache-ttl seconds are treated as missing (re-fetched)
The flags are absent on commands that declare no cache side effects

Schema

Types: response-envelope.md

meta.cache_used indicates whether any cached data was read during the invocation.

Wire Format

$ tool resolve --no-cache --output json

{
  "ok": true,
  "data": { "resolved": "1.2.3" },
  "error": null,
  "warnings": [],
  "meta": { "cache_used": false, "duration_ms": 1832 }
}

Example

Opt-in: automatically available on commands that declare a cache entry in filesystem_side_effects.

register command "resolve":
  filesystem_side_effects:
    - type: cache
      path: ~/.tool/cache/resolve/
      ttl: 3600
  # --no-cache and --cache-ttl are auto-registered by the framework

$ tool resolve --no-cache
→ meta.cache_used: false  # fresh fetch, no cache read or write

Requirement	Tier	Relationship
REQ-C-011	C	Provides: cache declarations that trigger these flags
REQ-F-043	F	Composes: temp files and caches share the session cleanup mechanism
REQ-O-027	O	Composes: `tool cleanup --scope cache` removes what `--no-cache` bypasses