Skip to content

Cache explain: inline run miss-reason + explain --json #21

Description

@no0dles

What to build

Add the two secondary reporting surfaces that reuse the explain engine from the keystone (#10):

  1. A verbosity/explain flag on hammerkit run that, when a task executes due to a cache miss, prints the miss cause and the changed input inline alongside the task's start — so cache-trust questions are answered during an ordinary run, not only via a separate command.
  2. hammerkit explain [task] --json emitting valid JSON with one entry per task carrying its predicted status and, for misses, the cause category and changed identifier — for CI gating/annotation.

Both consume the engine and persisted last-resolved record from the keystone; neither alters the cache hit/miss decision. Output routes through the Environment (no console.*).

References: specs/cache-explain/spec.md (US2 FR-005, US3 FR-006).

Acceptance criteria

  • Running with the verbosity/explain flag prints the miss cause + changed input alongside a task that executes due to a cache miss.
  • A task that is a cache hit prints no miss reason.
  • hammerkit explain <task> --json emits valid JSON listing each task's predicted status and, for misses, cause category + changed identifier.
  • Neither surface changes the cache hit/miss decision or exit codes.
  • Output routes through the Environment.

Blocked by

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyReady for an AFK agent to grab and implement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions