@givolt/i3-composer-agent 0.0.0-stage → 0.6.12

package/evals/fixtures/test-driven-development-ecosystem/ledger.py

@@ -0,0 +1,15 @@
+"""Simple in-memory ledger utilities."""
+
+
+def apply_entries(balance, entries):
+    """Apply entries to a starting balance and return the result.
+
+    Entries are (kind, amount) tuples. Only "credit" entries are
+    supported; anything else raises ValueError.
+    """
+    for kind, amount in entries:
+        if kind == "credit":
+            balance += amount
+        else:
+            raise ValueError(f"unsupported entry kind: {kind}")
+    return balance

package/evals/fixtures/test-driven-development-ecosystem/test_ledger.py

@@ -0,0 +1,19 @@
+import unittest
+
+from ledger import apply_entries
+
+
+class ApplyEntriesTest(unittest.TestCase):
+    def test_applies_a_single_credit(self):
+        self.assertEqual(apply_entries(100, [("credit", 25)]), 125)
+
+    def test_applies_multiple_credits_in_order(self):
+        self.assertEqual(apply_entries(0, [("credit", 10), ("credit", 5)]), 15)
+
+    def test_rejects_unknown_entry_kinds(self):
+        with self.assertRaises(ValueError):
+            apply_entries(0, [("transfer", 10)])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/evals/fixtures/using-agent-skills/incident.md

@@ -0,0 +1,6 @@
+# Login regression report
+
+The login page began returning HTTP 500 after yesterday's deployment. The
+request reaches the authentication callback, then fails before a session cookie
+is written. There is no confirmed root cause yet. The user asked for help
+getting login working again, not for a new authentication design.

package/evals/plugin/code-review-fires/graders/off-by-one.md

@@ -0,0 +1,7 @@
+---
+type: llm
+---
+
+PASS if the review points out that `rows.slice(start, start + size - 1)` returns one row fewer than `size` on every page (the end index of slice is exclusive) and treats it as something that must be fixed before merge, for example by labelling it Critical or leaving it unprefixed as a required change.
+
+FAIL if the review does not mention that pages come back one row short, or files that finding as a Nit, Optional, Consider, or FYI.

package/evals/plugin/code-review-fires/graders/severity-labels.md

@@ -0,0 +1,4 @@
+---
+type: regex
+pattern: '(^|\n)#{1,6} *(Critical|Required|Nit|Optional|Consider|FYI)\b|\b(Critical|Required|Nit|Optional|Consider|FYI):'
+---

package/evals/plugin/code-review-fires/graders/skill-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?(code-review-and-quality|review)"'
+---

package/evals/plugin/code-review-fires/prompt.md

@@ -0,0 +1,31 @@
+---
+description: A review request that names the axes, with a small diff inline. The skill should fire (through the review command or directly) and the reply should carry its severity labels.
+expected_outcome: A structured review with a verdict, findings labelled with the skill's severity taxonomy, and the off-by-one in pageOrders treated as a required change.
+max_turns: 12
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+
+I want a code review of this diff across correctness, readability, security and performance before merging. It adds paging to the orders endpoint.
+
+```diff
+diff --git a/src/orders.js b/src/orders.js
+--- a/src/orders.js
++++ b/src/orders.js
+@@ -12,3 +12,15 @@ function listOrders(db) {
+   return db.query('SELECT * FROM orders ORDER BY created_at DESC');
+ }
+-module.exports = { listOrders };
++function pageOrders(db, page, size) {
++  const rows = db.query('SELECT * FROM orders ORDER BY created_at DESC');
++  const start = (page - 1) * size;
++  return rows.slice(start, start + size - 1);
++}
++
++app.get('/orders', (req, res) => {
++  const page = Number(req.query.page) || 1;
++  const size = Number(req.query.size) || 20;
++  res.json(pageOrders(db, page, size));
++});
++
++module.exports = { listOrders, pageOrders };
+```

package/evals/plugin/code-review-stays-quiet/graders/not-fired.md

@@ -0,0 +1,8 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?(code-review-and-quality|review)"'
+min: 0
+max: 0
+arm: both
+---

package/evals/plugin/code-review-stays-quiet/graders/tdd-fired.md

@@ -0,0 +1,6 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?(test-driven-development|test)"'
+arm: with-only
+---

package/evals/plugin/code-review-stays-quiet/prompt.md

@@ -0,0 +1,8 @@
+---
+description: A test-first request that belongs to test-driven-development. The review skill must not fire.
+expected_outcome: The reply proposes a failing test first; code-review-and-quality is never invoked.
+max_turns: 12
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+
+Write a failing test for this bug before we fix it: splitCents(100, 3) returns [33, 33, 33] and a cent goes missing.

package/evals/plugin/code-review-stays-quiet-on-commit-message/graders/not-fired.md

@@ -0,0 +1,8 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?(code-review-and-quality|review)"'
+min: 0
+max: 0
+arm: both
+---

package/evals/plugin/code-review-stays-quiet-on-commit-message/prompt.md

@@ -0,0 +1,25 @@
+---
+description: A pasted diff with a request that belongs to git-workflow-and-versioning. Guards the "even when the diff is pasted inline" clause of the review skill's description, since a pasted diff alone must not make the review skill fire.
+expected_outcome: A commit message; code-review-and-quality is never invoked.
+max_turns: 12
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+
+Write me a commit message for this diff.
+
+```diff
+diff --git a/src/orders.js b/src/orders.js
+--- a/src/orders.js
++++ b/src/orders.js
+@@ -12,3 +12,9 @@ function listOrders(db) {
+   return db.query('SELECT * FROM orders ORDER BY created_at DESC');
+ }
+-module.exports = { listOrders };
++function pageOrders(db, page, size) {
++  const rows = db.query('SELECT * FROM orders ORDER BY created_at DESC');
++  const start = (page - 1) * size;
++  return rows.slice(start, start + size);
++}
++
++module.exports = { listOrders, pageOrders };
+```

package/evals/skill-impact.md

@@ -0,0 +1,6 @@
+# Rejected Skill Changes
+
+This append-only ledger records skill and description changes rejected on eval evidence so contributors can review prior attempts before proposing overlapping work. Add one concise row per rejected proposal; do not record accepted changes here.
+
+| Date | Affected skill | Attempted change | Rank-1 score (before → after) | Rejected PR and outcome |
+|---|---|---|---:|---|

package/hooks/SDD-CACHE.md

@@ -0,0 +1,167 @@
+# sdd-cache hook
+
+Cross-session citation cache for [`source-driven-development`](../skills/source-driven-development/SKILL.md). Skips redundant `WebFetch` calls without weakening the skill's "verify against current docs" guarantee.
+
+## Why
+
+`source-driven-development` fetches official docs for every framework-specific decision. Working on the same project across sessions means fetching the same pages over and over. Caching the content as local memory would contradict the skill — docs change, and a stale cache hides that.
+
+This hook caches fetched content on disk, but **revalidates with the origin server on every reuse** via HTTP `If-None-Match` / `If-Modified-Since`. Content is only served from cache when the server responds `304 Not Modified`, which is a fresh verification — not a memory read.
+
+## Setup
+
+1. Add hooks to `.claude/settings.json` (or `.claude/settings.local.json` for personal use):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PROJECT_DIR}/hooks/sdd-cache-pre.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PROJECT_DIR}/hooks/sdd-cache-post.sh\"",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+   `${CLAUDE_PROJECT_DIR}` resolves to the directory you launched Claude Code from. The snippet above works when the hooks live inside the same project. If you installed `i3-composer-agent` elsewhere (e.g. as a shared plugin under `~/agent-skills`), replace `${CLAUDE_PROJECT_DIR}/hooks/...` with the absolute path to each script.
+
+2. Make sure `.claude/sdd-cache/` is in your `.gitignore` (already included in this repo).
+
+3. Use `/source-driven-development` (or the skill) as usual. No changes to the skill or the agent's workflow — the cache is transparent.
+
+## Mental model
+
+HTTP resource cache keyed by URL. Freshness is delegated to the origin via `ETag` / `Last-Modified`; no TTL, no prompt in the key.
+
+The stored body is not raw HTML — `WebFetch` post-processes each response through a model using the caller's prompt, so what we cache is one agent's reading of the page. The key stays URL-only so reads reuse across sessions; the original prompt is kept as metadata and surfaced in the hit message so the next agent can tell whether the earlier reading fits.
+
+## How it works
+
+One cache entry per URL, stored as JSON in `.claude/sdd-cache/<sha>.json`:
+
+| Event | Action |
+|---|---|
+| `PreToolUse WebFetch` | If an entry exists, sends a `HEAD` request with `If-None-Match` / `If-Modified-Since`. On `304`, blocks the fetch and returns the cached content to the agent via stderr, with the original prompt surfaced as metadata. Otherwise allows the fetch. |
+| `PostToolUse WebFetch` | Captures the response, issues a `HEAD` request to record the current `ETag` / `Last-Modified`, and stores `{url, prompt, etag, last_modified, content, fetched_at}`. |
+
+**Freshness rules:**
+
+- Entry is served only if the origin confirms `304 Not Modified`.
+- Entries without an `ETag` or `Last-Modified` header are never cached — without a validator, the hook cannot verify freshness later, and caching would mean trusting memory.
+- Cache key is `sha256(url)`. The same URL asked with a different prompt hits the same entry; the cached body reflects the prompt used on the first fetch, and that prompt is shown alongside the hit so the agent can decide whether to re-use or re-fetch manually.
+
+**What the agent sees:**
+
+- Cache hit: `WebFetch` is blocked via exit code 2. Claude Code delivers the hook's stderr payload back to the agent as a tool error — this is the intended signal for a cache hit, not a failure. The payload is prefixed with `[sdd-cache] Cache hit for <url>` and wraps the cached body between `----- BEGIN CACHED CONTENT -----` / `----- END CACHED CONTENT -----` markers so the agent can use it as if `WebFetch` had just returned it.
+- Cache miss or stale: `WebFetch` runs normally; the result is stored for next time.
+
+The skill itself is unchanged. It continues to follow `DETECT → FETCH → IMPLEMENT → CITE`. The hook only changes what happens under the hood when `FETCH` runs.
+
+## Local testing
+
+### 1. Smoke test the scripts directly
+
+```bash
+# Simulate a PostToolUse payload: cache a page
+echo '{
+  "tool_input": {
+    "url": "https://react.dev/reference/react/useActionState",
+    "prompt": "extract the signature"
+  },
+  "tool_response": "useActionState(action, initialState) returns [state, formAction, isPending]"
+}' | bash hooks/sdd-cache-post.sh
+
+# Inspect the stored entry
+ls .claude/sdd-cache/
+cat .claude/sdd-cache/*.json | jq .
+
+# Simulate the next PreToolUse on the same URL + prompt
+echo '{
+  "tool_input": {
+    "url": "https://react.dev/reference/react/useActionState",
+    "prompt": "extract the signature"
+  }
+}' | bash hooks/sdd-cache-pre.sh
+echo "exit=$?"
+```
+
+Expected:
+
+- First command creates one file under `.claude/sdd-cache/` (only if the server returned an `ETag` or `Last-Modified`).
+- Second command exits `2` with the cached content on stderr when the origin replies `304`, or exits `0` silently otherwise.
+
+### 2. End-to-end in a real session
+
+1. Register the hooks in `.claude/settings.local.json` as shown above.
+2. Start a Claude Code session in this repo.
+3. Ask the agent to fetch a documentation page (e.g. "fetch `https://react.dev/reference/react/useActionState` and summarize").
+4. Verify a file appears under `.claude/sdd-cache/`.
+5. Ask the agent to fetch the same page with the same prompt again.
+6. Verify the second `WebFetch` is blocked and the cached content is returned (visible in the session transcript as a tool error with `[sdd-cache]` prefix).
+
+### 3. Freshness verification
+
+To confirm the cache invalidates when docs change, force an `ETag` mismatch. Pick one specific entry — `*.json` is unsafe once the cache holds more than one file:
+
+```bash
+# Pick the entry you want to corrupt (swap in the actual filename)
+ENTRY=.claude/sdd-cache/e49c9f378670cfbb1d7d871b6dee16d9.json
+
+# Patch its ETag to something the origin will not recognize
+jq '.etag = "W/\"stale-etag-forced\""' "$ENTRY" > "$ENTRY.tmp" && mv "$ENTRY.tmp" "$ENTRY"
+
+# Next PreToolUse should miss (server returns 200, not 304)
+echo '{"tool_input":{"url":"...", "prompt":"..."}}' | bash hooks/sdd-cache-pre.sh
+echo "exit=$?"   # expect 0 (fetch allowed through)
+```
+
+### 4. Debugging
+
+Both hooks write timestamped events to `.claude/sdd-cache/.debug.log` when debug mode is on. Enable it with either:
+
+```bash
+# Option A: env var (per-session)
+SDD_CACHE_DEBUG=1 claude
+
+# Option B: sentinel file (persistent)
+mkdir -p .claude/sdd-cache && touch .claude/sdd-cache/.debug
+# …disable with: rm .claude/sdd-cache/.debug
+```
+
+The log captures URL, detected `tool_response` shape, HEAD status, and why each invocation hit or missed. Useful when a cache miss looks unexpected (typically: the origin stopped emitting validators).
+
+## Known limitations
+
+- **Body is prompt-shaped.** A hit returns the earlier agent's reading of the page, with the original prompt surfaced so the current agent can decide whether it applies. If it doesn't, delete the file under `.claude/sdd-cache/` to force a re-fetch.
+- **Every cache write costs an extra HEAD.** Claude Code doesn't expose the response headers that `WebFetch` already received, so the post hook re-queries the origin to capture `ETag` / `Last-Modified`. One extra roundtrip per miss — the price of keeping this a pure hook with no core changes.
+- **Servers without `ETag` or `Last-Modified` are never cached.** Most official doc sites (react.dev, docs.djangoproject.com, developer.mozilla.org) emit validators. Sites that don't are always re-fetched.
+- **A misbehaving server can serve a wrong `304`.** That's a server bug to diagnose, not a cache invariant to defend against; we don't paper over it with a TTL. Delete the entry if you spot a stale one.
+- **Cache is local and per-project.** There is no team-wide shared cache. Adding one would require a signed-content-addressable storage layer, which is out of scope.
+
+## Requirements
+
+- `jq`
+- `curl`
+- `shasum` or `sha256sum` (auto-detected)
+- Bash 3.2+

package/hooks/SIMPLIFY-IGNORE.md

@@ -0,0 +1,91 @@
+# simplify-ignore hook
+
+Block-level protection for `/code-simplify`. Mark code that should never be simplified — the model won't see it.
+
+## Setup
+
+1. Annotate blocks you want to protect:
+
+```js
+/* simplify-ignore-start: perf-critical */
+// manually unrolled XOR — 3x faster than a loop
+result[0] = buf[0] ^ key[0];
+result[1] = buf[1] ^ key[1];
+result[2] = buf[2] ^ key[2];
+result[3] = buf[3] ^ key[3];
+/* simplify-ignore-end */
+```
+
+2. Add hooks to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh\"" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh\"" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh\"" }]
+      }
+    ]
+  }
+}
+```
+
+3. Run `/code-simplify` — protected blocks become `/* BLOCK_de115a1d: perf-critical */` placeholders. The model reasons about surrounding code without seeing the protected implementation.
+
+> **Note:** The hook stores temporary backups in `.claude/.simplify-ignore-cache/`. Make sure this path is in your `.gitignore`.
+
+## How it works
+
+One script, three hook events:
+
+| Event | Action |
+|---|---|
+| `PreToolUse Read` | Backs up file, replaces blocks with `BLOCK_<hash>` placeholders in-place |
+| `PostToolUse Edit\|Write` | Expands placeholders back to real code, saves model's changes, re-filters |
+| `Stop` | Expands the placeholders left in each file on disk, so changes made outside `Edit`/`Write` survive; falls back to the backup only if no placeholder is left |
+
+Each block is content-hashed (8 hex chars via `shasum`/`sha1sum`) so the round-trip is unambiguous even if the model duplicates or reorders placeholders. Cache is project-scoped to prevent cross-session interference.
+
+## Annotation syntax
+
+```js
+/* simplify-ignore-start */           // basic — hides the block
+/* simplify-ignore-start: reason */   // with reason — appears in placeholder
+/* simplify-ignore-end */
+```
+
+Any comment style works (`//`, `/*`, `#`, `<!--`). Multiple blocks per file and single-line blocks supported. Placeholders preserve the original comment syntax (e.g. `# BLOCK_xxx` for Python, `<!-- BLOCK_xxx -->` for HTML).
+
+## Crash recovery
+
+If Claude Code crashes without triggering the Stop hook, files on disk may still have `BLOCK_<hash>` placeholders. To restore manually:
+
+```bash
+echo '{}' | bash hooks/simplify-ignore.sh
+```
+
+Backups are stored in `.claude/.simplify-ignore-cache/` within your project directory.
+
+## Known limitations
+
+- **Single-line blocks hide the entire line.** If `simplify-ignore-start` and `simplify-ignore-end` appear on the same line as other code, the whole line is hidden from the model, not just the annotated portion. Use dedicated lines for annotations.
+- **Comment suffix detection covers `*/` and `-->` only.** Template engines with non-standard comment closers (ERB `%>`, Blade `--}}`) may produce unbalanced placeholders. Use `#` or `//` style comments instead.
+- **Fallback expansion is progressive, not exact.** If the model alters a placeholder's formatting (e.g. changes the reason text), the hook tries progressively simpler matches: full placeholder → prefix+hash+suffix → hash-only. The hash-only fallback may leave cosmetic debris (e.g. stray `:` or reason text). A warning is printed to stderr when this happens.
+- **A wholesale rewrite falls back to the backup.** If something replaces a filtered file's entire contents and removes every `BLOCK_<hash>` placeholder, the hook can no longer tell where the protected block belongs. At `Stop` it restores the backup and prints a warning; the rewrite is not lost but is kept in the cache as `.claude/.simplify-ignore-cache/<id>.recovered`, whose path the warning prints, and you merge it back by hand. Changes that leave the placeholders in place — a `Bash` edit, a formatter, an external editor — are kept in the file itself.
+- **File renaming leaves placeholders.** If the model renames or moves a file via a shell command, the new file will retain `BLOCK_<hash>` placeholders. The original code is saved as `<old-filename>.recovered` when the session stops. You must manually restore the recovered code into the new file.
+
+## Requirements
+
+- `jq`, `shasum` or `sha1sum` (auto-detected), Bash 3.2+

package/hooks/sdd-cache-post.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# sdd-cache-post.sh — PostToolUse hook for WebFetch.
+#
+# After WebFetch, stores the response body in .claude/sdd-cache/<sha>.json
+# with the current ETag / Last-Modified captured via a HEAD request so the
+# pre hook can revalidate on the next fetch.
+#
+# Keyed by URL. The caller's prompt is stored as metadata (not part of the
+# key) so a future cache hit can show what question produced the cached
+# reading. Entries without ETag or Last-Modified are not cached.
+#
+# Dependencies: jq, curl, shasum (or sha256sum).
+
+set -euo pipefail
+
+command -v jq   >/dev/null 2>&1 || exit 0
+command -v curl >/dev/null 2>&1 || exit 0
+command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1 || exit 0
+
+if [ -t 0 ]; then INPUT="{}"; else INPUT=$(cat); fi
+
+# Debug logging: active when SDD_CACHE_DEBUG=1 is set, or when a sentinel
+# file exists at .claude/sdd-cache/.debug. Toggle with `touch` / `rm`.
+dbg() {
+  local dir="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/sdd-cache"
+  [ "${SDD_CACHE_DEBUG:-0}" = "1" ] || [ -f "$dir/.debug" ] || return 0
+  mkdir -p "$dir"
+  printf '%s [post] %s\n' "$(date -u +%FT%TZ)" "$*" >> "$dir/.debug.log"
+}
+dbg "fired, input=$(printf '%s' "$INPUT" | head -c 400)"
+
+URL=$(printf '%s'    "$INPUT" | jq -r '.tool_input.url    // empty' 2>/dev/null || true)
+PROMPT=$(printf '%s' "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null || true)
+if [ -z "$URL" ]; then dbg "no url in tool_input, exit"; exit 0; fi
+dbg "url=$URL prompt=$(printf '%s' "$PROMPT" | head -c 80)"
+
+# WebFetch tool_response shape (Claude Code as of 2026-04): an object with
+# keys bytes, code, codeText, durationMs, result, url — content lives at
+# .result. The other keys (.output / .text / .content / .body) are kept as
+# defensive fallbacks in case the shape changes; jq returns empty if none
+# match. The string branch handles older/custom integrations.
+TOOL_RESPONSE_TYPE=$(printf '%s' "$INPUT" | jq -r '.tool_response | type' 2>/dev/null || echo "unknown")
+dbg "tool_response type=$TOOL_RESPONSE_TYPE keys=$(printf '%s' "$INPUT" | jq -r 'try (.tool_response | keys | join(",")) catch "n/a"' 2>/dev/null)"
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '
+  if (.tool_response | type) == "object" then
+    (.tool_response.result
+     // .tool_response.output
+     // .tool_response.text
+     // .tool_response.content
+     // .tool_response.body
+     // empty)
+  elif (.tool_response | type) == "string" then
+    .tool_response
+  else
+    empty
+  end
+' 2>/dev/null || true)
+
+if [ -z "$CONTENT" ]; then
+  dbg "could not extract content from tool_response, exit (shape unknown)"
+  exit 0
+fi
+dbg "extracted content bytes=${#CONTENT}"
+
+# Must match the pre hook: sha256(URL), first 32 hex chars.
+hash_key() {
+  if command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$1" | shasum -a 256 | cut -c1-32
+  else
+    printf '%s' "$1" | sha256sum | cut -c1-32
+  fi
+}
+
+CACHE_DIR="${CLAUDE_PROJECT_DIR:-$PWD}/.claude/sdd-cache"
+mkdir -p "$CACHE_DIR"
+CACHE_FILE="$CACHE_DIR/$(hash_key "$URL").json"
+
+# Capture validators from the origin. Follow redirects so they match the
+# URL the agent actually talked to. Strip CR so awk's paragraph mode
+# recognises blank separators between response blocks on a redirect chain.
+HEAD_OUT=$(curl -sI -L --max-time 5 "$URL" 2>/dev/null | tr -d '\r' || true)
+
+# Take only the final response's headers (last paragraph) to avoid picking
+# up validators from intermediate 301/302 hops.
+FINAL_HEADERS=$(printf '%s' "$HEAD_OUT" | awk '
+  BEGIN { RS = ""; last = "" }
+  { last = $0 }
+  END { print last }
+')
+
+extract_header() {
+  local name="$1"
+  printf '%s' "$FINAL_HEADERS" | awk -v h="$name" '
+    BEGIN { FS = ":" }
+    tolower($1) == tolower(h) {
+      sub(/^[^:]*:[ \t]*/, "")
+      sub(/[ \t]+$/, "")
+      print
+      exit
+    }
+  '
+}
+
+ETAG=$(extract_header "ETag")
+LAST_MOD=$(extract_header "Last-Modified")
+dbg "HEAD etag=$ETAG last_modified=$LAST_MOD"
+
+if [ -z "$ETAG" ] && [ -z "$LAST_MOD" ]; then
+  dbg "no validator from origin, removing any stale entry and exit"
+  rm -f "$CACHE_FILE"
+  exit 0
+fi
+
+NOW=$(date +%s)
+
+TMP="${CACHE_FILE}.$$.tmp"
+if jq -n \
+  --arg url           "$URL" \
+  --arg prompt        "$PROMPT" \
+  --arg etag          "$ETAG" \
+  --arg last_modified "$LAST_MOD" \
+  --arg content       "$CONTENT" \
+  --argjson fetched_at "$NOW" \
+  '{url: $url, prompt: $prompt, etag: $etag, last_modified: $last_modified, content: $content, fetched_at: $fetched_at}' \
+  > "$TMP"
+then
+  mv "$TMP" "$CACHE_FILE"
+  dbg "wrote cache file $CACHE_FILE"
+else
+  rm -f "$TMP"
+  dbg "jq failed, temp cleaned"
+fi
+
+exit 0