Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/inc2-incident-overlay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An incident overlay renderer (`docs/assets/readme/incident-overlay.mjs`, `render-incident.mjs`) that draws one incident on the published harness figure from a small JSON, and its first picture, `v2/incidents/claude-settings-secrets.png`.
58 changes: 58 additions & 0 deletions docs/assets/readme/incident-overlay.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
// Incident overlay: the published harness figure (where-chock-sits.mjs, unchanged) with one incident drawn on it. The spec JSON names the path, the numbered steps, the ringed catch points and the refusal text; layout and colours come from the figure.
import { layout, where, DEFAULT_PALETTE } from './where-chock-sits.mjs';

// The order layout() pushes its arrows in; a test asserts the count so a layout change cannot shift the names silently.
export const EDGES = ['you-prompt', 'prompt-loop', 'session-loop', 'context-loop', 'loop-model', 'loop-gate', 'gate-loop', 'gate-tools', 'tools-loop', 'tools-external', 'loop-subagents', 'tools-commit', 'commit-push', 'push-ci', 'ci-main'];
const RED = '#DC2626';
const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;');
const abs = (x, y, w, h, css, inner = '') => `<div style="position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;${css}">${inner}</div>`;

const corners = (d) => [...d.matchAll(/([MHV])(-?[\d.]+)(?: (-?[\d.]+))?/g)].reduce((pts, m) => {
const [x, y] = pts.length ? pts[pts.length - 1] : [0, 0];
pts.push(m[1] === 'M' ? [+m[2], +m[3]] : m[1] === 'H' ? [+m[2], y] : [x, +m[2]]);
return pts;
}, []);
// A point a third of the way along the segment's longest straight run, where a numbered mark fits beside the arrow label.
const markAt = (d) => {
const p = corners(d), runs = p.slice(1).map((q, i) => [p[i], q]);
const [a, b] = runs.reduce((best, r) => (Math.hypot(r[1][0] - r[0][0], r[1][1] - r[0][1]) > Math.hypot(best[1][0] - best[0][0], best[1][1] - best[0][1]) ? r : best));
return [a[0] + (b[0] - a[0]) * 0.3, a[1] + (b[1] - a[1]) * 0.3];
};

export const checkSpec = (L, spec) => {
if (L.segs.length !== EDGES.length) throw new Error(`layout has ${L.segs.length} arrows, EDGES names ${EDGES.length}`);
const unknown = [...spec.path.edges, ...spec.steps.map((s) => s.edge)].filter((e) => !EDGES.includes(e));
if (unknown.length) throw new Error(`unknown edge ${unknown}`);
const ids = new Set(L.badges.map((b) => b.p.id)), cards = new Set(Object.keys(L.cards));
[...spec.rings, ...spec.dashed].filter((r) => !ids.has(r.point)).forEach((r) => { throw new Error(`no badge ${r.point}`); });
spec.path.cards.filter((c) => !cards.has(c)).forEach((c) => { throw new Error(`no card ${c}`); });
};

export const incident = (page, W, spec, palette = DEFAULT_PALETTE) => {
const base = JSON.parse(JSON.stringify(W));
base.harness.title = spec.title;
const L = layout(base);
checkSpec(L, spec);
const { paper: PAPER, ink: INK, soft: SOFT, line: LINE } = palette;
const edge = (e) => L.segs[EDGES.indexOf(e)];
const dim = Object.values(L.cards).filter((c) => !spec.path.cards.includes(c.id)).map((c) => abs(c.x, c.y, c.w, c.h, `background:${PAPER};opacity:.62;border-radius:12px`)).join('');
const marker = `<marker id="r" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" refX="11" refY="7" orient="auto"><path d="M2 2 L12 7 L2 12" fill="none" stroke="${RED}" stroke-width="2.4"/></marker>`;
const lines = spec.path.edges.map((e) => `<path d="${edge(e).d}" fill="none" stroke="${RED}" stroke-width="3" stroke-linejoin="round" marker-end="url(#r)"/>`).join('');
const disc = (x, y, text, size = 20) => abs(x - size / 2, y - size / 2, size, size, `border-radius:50%;background:${RED};color:#fff;font-size:12px;font-weight:700;line-height:${size}px;text-align:center`, esc(text));
const steps = spec.steps.map((s, i) => { const [x, y] = markAt(edge(s.edge).d); return disc(x, y, i + 1); }).join('');
const ringed = (r, i, dashed) => { const b = L.badges.find((q) => q.p.id === r.point), g = 3; return abs(b.x - g, b.y - g, b.w + 2 * g, b.h + 2 * g, `box-sizing:border-box;border:3px ${dashed ? 'dashed' : 'solid'} ${RED};border-radius:999px`) + disc(b.x + b.w + g, b.y - g, String.fromCharCode(65 + i), 18); };
const rings = spec.rings.map((r, i) => ringed(r, i, false)).join('') + spec.dashed.map((r, i) => ringed(r, spec.rings.length + i, true)).join('');
const cropH = 78 + L.Ht + 20 + 56;
const frame = where((body) => body, base, palette);
const overlay = `<div style="position:absolute;left:20px;top:78px;width:840px;height:${L.Ht}px">${dim}<svg width="840" height="${L.Ht}" style="position:absolute;left:0;top:0" xmlns="http://www.w3.org/2000/svg"><defs>${marker}</defs>${lines}</svg>${steps}${rings}</div>`;
const row = (mark, text, round) => `<div style="display:flex;gap:10px;align-items:flex-start;margin-top:8px"><span style="flex:none;width:20px;height:20px;line-height:20px;text-align:center;font-size:12px;font-weight:700;color:#fff;background:${RED};border-radius:${round ? '50%' : '4px'}">${mark}</span><span style="font-size:14px;line-height:20px;color:${INK}">${esc(text)}</span></div>`;
const key = spec.steps.map((s, i) => row(i + 1, s.text, true)).join('') + spec.rings.map((r, i) => row(String.fromCharCode(65 + i), r.label, false)).join('') + spec.dashed.map((r, i) => row(String.fromCharCode(65 + spec.rings.length + i), r.label, false)).join('') + (spec.dashed.length ? `<div style="margin-top:10px;font-size:13px;color:${SOFT}">solid ring: a check the proof ran and recorded. dashed ring: a place a rule can be added.</div>` : '');
const refusals = spec.refusals.length
? spec.refusals.map((r) => `<div style="margin-top:10px"><div style="font-size:13px;font-weight:700;color:${SOFT}">${esc(r.sample)}: exit ${esc(r.exit)}</div><pre class="mono" style="margin:4px 0 0;white-space:pre-wrap;font-size:13px;line-height:1.5;color:${INK}">${esc(r.text)}</pre></div>`).join('')
: `<div class="mono" style="margin-top:10px;font-size:13px;color:${SOFT}">no proof recorded yet</div>`;
return page(`<div id="incident" style="width:880px;background:${PAPER};color:${INK};position:relative">
<div style="position:relative;width:880px;height:${cropH}px;overflow:hidden">${frame}${overlay}</div>
<div style="padding:0 40px 20px"><div style="font-size:12px;font-weight:700;letter-spacing:.06em;text-transform:uppercase;color:${SOFT}">${esc(spec.path.title)}</div>${key}
<div style="margin-top:16px;padding:12px 16px;border:1.5px solid ${LINE};border-radius:12px;background:${palette.chip}"><div style="font-size:12px;font-weight:700;letter-spacing:.06em;text-transform:uppercase;color:${SOFT}">${esc(spec.refusal_title)}</div>${refusals}</div>
<div style="margin-top:16px;font-size:16px;color:${SOFT}">${esc(spec.footer)}</div></div></div>`);
};
81 changes: 81 additions & 0 deletions docs/assets/readme/incidents/claude-settings-secrets.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
{
"_": "Per-incident spec read by incident-overlay.mjs. 'rings' (solid) stay empty until a proof run records a refusal at that badge; only recorded refusals may be ringed. 'dashed' marks places a rule can be added; its labels never claim the point caught the incident.",
"title": "Keep the agent's local settings out of git",
"path": {
"title": "The path, in red",
"edges": [
"you-prompt",
"prompt-loop",
"loop-gate",
"gate-tools",
"tools-commit",
"commit-push",
"push-ci",
"ci-main"
],
"cards": [
"you",
"prompt",
"loop",
"gate",
"tools",
"commit",
"push",
"ci",
"main"
]
},
"steps": [
{
"edge": "gate-tools",
"text": "You approve \"Yes, and don't ask again\" on a command that carries a secret."
},
{
"edge": "tools-commit",
"text": "The command, secret included, is saved to .claude/settings.local.json in the project."
},
{
"edge": "commit-push",
"text": "git commit takes the file along with the rest of the code."
},
{
"edge": "push-ci",
"text": "git push puts it in the repository, public or not."
}
],
"rings": [
{
"point": "git-commit",
"label": "commit: scan-secrets refuses the staged settings file (exit 1)"
}
],
"refusal_title": "What the checks printed",
"refusals": [
{
"sample": "git commit, sample a (API key in the right provider format)",
"exit": "1",
"text": "Potential secret detected in this change. Remove credentials and rotate any exposed keys. ...\n- .claude/settings.local.json: content pattern"
},
{
"sample": "git commit, sample b (password in a connection string)",
"exit": "1",
"text": "Potential secret detected in this change. Remove credentials and rotate any exposed keys. ...\n- .claude/settings.local.json: content pattern"
}
],
"footer": "The example rules here are from Chock.",
"alt": "The published harness figure with the incident's path drawn in red: you approve a command that carries a secret, the agent loop runs it through the tool gate, the tool saves it to the settings file, and git commit, git push, CI and the main branch carry it on. Cards off the path are dimmed. A solid ring on the commit badge marks the check that refused two test files at commit; dashed rings mark three places a rule could be added.",
"dashed": [
{
"point": "prompt_submit",
"label": "your own rule could check here: a secret pasted into the prompt, before it reaches the model and the saved transcript"
},
{
"point": "pre_tool",
"label": "a rule could check here: the proposed command that carries the secret, before it runs"
},
{
"point": "file_changed",
"label": "a rule could notice here, before the commit: the settings file now holds a secret (warns; it cannot undo the write)"
}
]
}
27 changes: 27 additions & 0 deletions docs/assets/readme/render-incident.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
// Renders one incident overlay to PNG: node docs/assets/readme/render-incident.mjs <slug> [out.png] (needs `playwright`; CHROMIUM=/path to use a preinstalled Chromium)
import { chromium } from 'playwright';
import { mkdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
import { incident } from './incident-overlay.mjs';

const HERE = path.dirname(fileURLToPath(import.meta.url));
const [slug, out = path.join(HERE, 'v2', 'incidents', `${slug}.png`)] = process.argv.slice(2);
const read = (...p) => JSON.parse(readFileSync(path.join(HERE, ...p), 'utf8'));
const CSS = `*{box-sizing:border-box}body{margin:0;background:#FBF7EE;font-family:"Instrument Sans",system-ui,sans-serif;font-weight:500}.mono{font-family:"JetBrains Mono",ui-monospace,monospace}.eyebrow{font-family:"JetBrains Mono",ui-monospace,monospace;letter-spacing:.14em;text-transform:uppercase}`;
const page = (body) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><link href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400..700&family=JetBrains+Mono:wght@400..700&display=swap" rel="stylesheet"><style>${CSS}</style></head><body>${body}</body></html>`;
const html = incident(page, read('where-chock-sits.json'), read('incidents', `${slug}.json`));
const browser = await chromium.launch({ executablePath: process.env.CHROMIUM || undefined, args: ['--no-sandbox'] });
const pg = await (await browser.newContext({ deviceScaleFactor: 2 })).newPage();
await pg.setViewportSize({ width: 880, height: 800 });
await pg.setContent(html, { waitUntil: 'networkidle' });
const ok = await pg.evaluate(async () => {
const fonts = ['16px "Instrument Sans"', '600 16px "Instrument Sans"', '14px "JetBrains Mono"'];
await Promise.all(fonts.map((f) => document.fonts.load(f)));
return fonts.map((f) => document.fonts.check(f));
});
if (!ok.every(Boolean)) throw new Error(`fonts missing (Instrument Sans / JetBrains Mono): ${ok}`);
mkdirSync(path.dirname(out), { recursive: true });
await pg.locator('#incident').screenshot({ path: out });
await browser.close();
console.log(out);
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
63 changes: 63 additions & 0 deletions tests/test_incident_overlay.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
"""The incident overlay draws only on the published harness figure, rings only recorded refusals and keeps the product name in the footer."""

from __future__ import annotations

import json
import shutil
import struct
import subprocess

import pytest
from readme_figure_support import ASSETS, FIGURE, ROOT

SLUG = "claude-settings-secrets"
SPEC = json.loads((ASSETS / "incidents" / f"{SLUG}.json").read_text(encoding="utf-8"))
PNG = ASSETS / "v2" / "incidents" / f"{SLUG}.png"
POINTS = {p["id"] for p in FIGURE["points"]}


def _node(script: str) -> str:
node = shutil.which("node")
if not node:
pytest.skip("node is not installed")
done = subprocess.run(
[node, "--input-type=module", "-e", script], cwd=ROOT, capture_output=True, text=True, check=False
)
assert done.returncode == 0, done.stderr
return done.stdout


def test_png_exists_and_is_the_size_the_page_renders_at() -> None:
assert PNG.stat().st_size > 10_000
width, height = struct.unpack(">II", PNG.read_bytes()[16:24])
assert width == 1760 and height > 2000


def test_overlay_builds_without_a_crowded_card_and_edges_match_the_layout() -> None:
script = (
"import {incident, EDGES} from './docs/assets/readme/incident-overlay.mjs';"
"import {layout, crowded} from './docs/assets/readme/where-chock-sits.mjs';"
"import {readFileSync} from 'node:fs';"
"const r = (p) => JSON.parse(readFileSync(p, 'utf8'));"
f"const W = r('docs/assets/readme/where-chock-sits.json'), S = r('docs/assets/readme/incidents/{SLUG}.json');"
"incident((b) => b, W, S);"
"console.log(JSON.stringify({crowded: crowded(layout(W)), edges: layout(W).segs.length === EDGES.length}));"
)
assert json.loads(_node(script)) == {"crowded": [], "edges": True}


def test_every_ring_is_a_real_badge_and_solid_rings_have_a_recorded_refusal() -> None:
assert {r["point"] for r in SPEC["rings"] + SPEC["dashed"]} <= POINTS
assert not {r["point"] for r in SPEC["rings"]} & {r["point"] for r in SPEC["dashed"]}
assert SPEC["rings"] and SPEC["refusals"]
assert all(r["exit"] == "1" and "Potential secret detected" in r["text"] for r in SPEC["refusals"])


def test_dashed_labels_never_claim_a_catch() -> None:
for ring in SPEC["dashed"]:
assert "could" in ring["label"] and "caught" not in ring["label"] and "refuse" not in ring["label"]


def test_the_product_name_is_only_in_the_footer() -> None:
text = json.dumps({k: v for k, v in SPEC.items() if k not in ("_", "footer", "alt")}).lower()
assert "chock" not in text and "chock" in SPEC["footer"].lower()