feat(apply,verify): validate-then-fetch freshness check to cut context bloat

[thekkagent]

Problem

/beat:apply and /beat:verify re-read all spec artifacts (and often whole source files) every time the skill is entered, with no freshness check. In long, iterative runs (apply → verify → fix → re-verify …) within a single resumed session, this fills the model's context with duplicate copies of unchanged files — driving cost up, recall down (context rot), and eventually forcing lossy compaction. The recipe is optimized for cold start; run warm/resumed, the always-refetch assumption mismatches and the reads become redundant.

Approach

Treat the filesystem/git as the source of truth and the in-context copy as a cache — validate-then-fetch instead of always-refetch. Pure instruction edits to two skills (no runtime code, no schema changes, no new reference doc).

apply

• Step 3 rewritten: cold start reads fully (unchanged); on re-entry, validate with git status --short beat/changes/<name>/ and re-read only what changed, reusing the in-context copy otherwise.
• Targeted ranges (offset/limit) when reorienting on a large unchanged file.
• Compaction safety net: if git status shows unchanged but the content can't be recalled (likely compacted away), re-read it — targeted, not blind whole-file.
• Self-edit trust: don't re-read a file you just edited to "confirm" it.
• Guardrail reworded (grounding can come from a still-valid in-context copy); Rationalization table + Red Flags added, cutting both ways (against over-reading and against trusting compacted-away content).

verify

• Main session is forbidden from self-verifying — it only forwards artifacts to fresh subagents. So Step 2 now reads only the small routing files (status.yaml, config.yaml) and collects artifact paths instead of reading large artifacts into context.
• Step 3 passes artifact paths (not pasted contents) to the verification subagent; verification-subagent-prompt.md updated so the subagent reads them itself (more independent — raw disk, no transcription drift; also prompt-cache safe). code-reviewer-prompt.md already took paths/git-range — no change.

Testing

• Deterministic checks pass: node scripts/sync-references.mjs --check (references in sync) and content-presence checks across all edited skills.
• tests/skill-content/test-apply-enforcement.sh (+2 assertions) and test-verify-enforcement.sh (+1 assertion) added for the new rules. These run via claude -p headless and should be exercised in CI.

Non-goals

No persisting validators (hash/SHA) into status.yaml; no changes to plan/design/distill/archive/explore (run ~once per change, marginal payoff); no runtime scripts.

🤖 Generated with Claude Code