@natjswenson/devlog 0.11.0 → 0.11.1

package/evals/baseline/published/devlog-v0.8.1.md

@@ -0,0 +1,97 @@
+---
+title: "Encoding the fix into the skill, not just the code: how one agent session backfilled 49 cover images"
+date: 2026-07-16
+project: devlog
+version: v0.8.1
+tags: [claude-code, skills, subagents, ai-agents, devlog, image-generation, playwright]
+summary: "devlog v0.8.1 fixed bland, repetitive cover images, but the fix that stuck wasn't in the render code. It was a line added to the skill's own instructions and a machine-checked invariant, which is what let one Claude Code session regenerate all 49 backfilled covers in parallel and get them right the second time."
+---
+
+## Shipped
+
+devlog v0.7.0 through v0.8.1 added a `private` project type and a full cover-image pipeline: every post gets a rendered 1600x900 PNG from a headless browser, feeding the feed thumbnail, post hero, OG card, and RSS enclosure. The render pipeline (Playwright screenshotting an HTML/SVG document, `sharp` for palette quantization) is real code and it's covered further down, but it's not the interesting part of this release.
+
+The interesting part is that the first batch of 49 backfilled covers all looked the same, one shared template, and the fix wasn't a code change at all. It was rewriting the skill's own instructions and adding a rule the skill checks for itself, then letting one agent session regenerate every cover from that new instruction, in parallel, without a human opening an image editor.
+
+## The skill file is the product, not the render code
+
+`devlog` is a Claude Code skill: a `SKILL.md` plus supporting files that Claude loads when composing a release. Skills exist for exactly this shape of problem. The Claude Code docs put it directly: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it" ([Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills)). The cover-composition procedure, the palette, the font, the "never do this" list, all of it lives in files an agent reads at the moment it needs them, not in a prompt retyped every release.
+
+The first version of that procedure described a palette and a font and left composition open: a title, a kicker, an optional shape. Every one of the 49 backfilled covers took that literally, big headline text, one of three rotating stock shapes in a corner. Technically correct, visually identical, and a waste of the space.
+
+The fix went into `SKILL.md` itself, as an instruction the agent has to follow before it's allowed to compose a cover:
+
+```text
+# 2. Compose the cover using ONLY this release's title/tags/summary/`## Shipped` text
+#    (never the raw draft file, never `## Changelog`) plus the returned style guide and
+#    reference images. A cover that just re-renders the title in large text is a failure —
+#    find the one concrete mechanism this release is actually about (not the project name,
+#    not "a bug fix") and draw ONE custom inline-SVG illustration of it, sized as the
+#    dominant visual element of the canvas; title/kicker stay secondary. Two different
+#    releases should never produce visually similar covers...
+```
+
+And it went into `skill-invariants.json`, a second, independent list of rules the skill checks itself against, separate from the step-by-step instructions:
+
+```json
+{
+  "id": "cover-custom-illustration",
+  "pattern": "cover that just re-renders the title in large text is a failure",
+  "rationale": "First shipped version of this feature produced a shared text-heavy template with a rotating stock shape — rejected as bland/repetitive. Losing this line reopens that regression."
+}
+```
+
+The `rationale` field is the part worth noticing. It doesn't describe what the rule does, the pattern line already does that. It records why the rule exists, so the next time someone (or some agent) is tempted to trim that sentence from `SKILL.md` as boilerplate, the invariant file is right there explaining what regression comes back if they do. A skill without that second file just has good intentions that erode one edit at a time.
+
+## What let one session redo 49 images: subagents, not a loop
+
+Rewriting the style guide fixes new posts. It does nothing for 49 already-published ones sitting on disk with the old bland covers. Regenerating all of them serially, in the same conversation, one render-review-adjust cycle at a time, would have flooded that conversation with 49 rounds of image output long before it reached the last one.
+
+Claude Code's subagents exist for that specific shape of problem. Per the docs: "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions" ([Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents)). Seven of them ran in parallel, each working a batch of the 49 posts against the new style guide and invariant, each returning only the finished covers rather than the back-and-forth it took to get there. The main session stayed free to keep working on the render pipeline and the site-side bugs below while the batches came back.
+
+That split, one thread holding the plan and doing the review, several isolated threads doing the repetitive regeneration, is what made "redo all 49, today" a reasonable thing to ask for instead of a multi-day queue of manual image tweaks.
+
+## Build it: the part that's still ordinary code
+
+The render step itself is unglamorous by comparison: build an HTML string with CSS and hand it to a headless browser to screenshot, the same approach Playwright's own docs describe, where "the browser handles fonts, gradients, flexbox, and every other CSS feature" for you ([Playwright: Screenshots](https://playwright.dev/docs/screenshots)). Launch the browser, set a fixed viewport, load the HTML, wait for the bundled font to actually finish loading before the screenshot (`document.fonts.ready`, which per MDN "will only resolve once the document has completed loading fonts... and no further font loads are needed" ([MDN: FontFaceSet.ready](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready))), then hand the screenshot to `sharp` with `palette: true` for quantization. Skip the wait and every cover silently renders in the fallback sans-serif; nothing throws.
+
+```js
+export async function renderCover(html, { width = 1600, height = 900 } = {}) {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage({ viewport: { width, height } });
+    await page.setContent(html, { waitUntil: 'load' });
+    await page.addStyleTag({ content: fontFaceCss });
+    await page.evaluate((f) => document.fonts.load(`1em '${f}'`), FONT_FAMILY);
+    await page.evaluate(() => document.fonts.ready);
+    const png = await page.screenshot({ type: 'png' });
+    return await sharp(png).png({ palette: true }).toBuffer();
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+Quantization is a real size win for flat illustrations specifically: the same 1600x900 test render came out at 27306 bytes with plain PNG encoding and 4989 bytes with `palette: true`. It's the wrong setting for anything with a smooth gradient, one more reason the style guide asks for flat, limited color instead.
+
+## Gotchas
+
+**A style guide that only describes the palette gets you a consistent palette and nothing else.** The part that needed to be explicit, in writing, in the file the agent actually reads, was the part everyone assumed went without saying: don't just render the title. Leaving it implicit is how the first 49 covers all ended up looking the same.
+
+**A local content cache silently overrode the field that made covers work at all.** The site that consumes these covers keeps a local copy of already-published posts for editorial preview, and that local copy wins over the remote source when both exist, which is nearly all posts. It had no `cover` field, so the merge defaulted every cover-bearing post back to "no cover" the moment it also had a local copy. Only 1 of the first 49 backfilled covers actually rendered on the live site until this shipped, caught by rebuilding the site and checking real output instead of trusting the pipeline.
+
+**Once the cover carried the title, the plain-text heading above it duplicated it.** A covered post showed the same headline twice, once in the image, once in the `<h1>` right above it. The fix drops the separate heading for covered posts and lets the card, image plus a caption line for date and read time, be the visible heading, while a screen-reader-only `<h1>` keeps one real heading in the page structure.
+
+## Sources
+
+- [Claude Code docs: Extend Claude with skills](https://code.claude.com/docs/en/skills) — confirms skills load reference material on demand rather than living in the always-loaded CLAUDE.md.
+- [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents) — confirms each subagent runs in an isolated context window, which is what made parallel batches of the 49-cover regeneration practical.
+- [MDN: FontFaceSet.ready](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet/ready) — the exact resolution condition for waiting on font loads before a screenshot.
+- [Playwright: Screenshots](https://playwright.dev/docs/screenshots) — confirms the "build HTML, screenshot it" approach the render step relies on.
+
+## Changelog
+
+- fix(devlog): cover style guide mandates one custom illustration per post (0.8.1) ([ef46024](https://github.com/natejswenson/claude-skills/commit/ef460249b421ce9242ec121f982037e64e650ba0))
+- feat(devlog): auto-generate cover images for every post (v0.8.0) (#72) ([88d4c96](https://github.com/natejswenson/claude-skills/commit/88d4c96a176458f7f30d23e1307ddacab2b86829))
+- feat(devlog): add a private project type (v0.7.0) ([21f418a](https://github.com/natejswenson/claude-skills/commit/21f418a249f82869e66f27e38956dbc00044ae5b))
+- feat(devlog): tag cap raise, validation, manifest write-through (#71) ([b699bc1](https://github.com/natejswenson/claude-skills/commit/b699bc1e8cdfd580a97b903896d357fe22f6dbe2))

package/evals/baseline/published/devlog-v0.9.0.md

@@ -0,0 +1,193 @@
+---
+title: "Enforcing a layout contract on AI-drawn images with a DOM geometry gate"
+date: 2026-07-18
+project: devlog
+version: v0.9.0
+tags: [playwright, llm-agents, image-generation, dom, getboundingclientrect, validation, svg, headless-chromium]
+summary: "Style-guide prose can ask an agent to draw inside a box; it can't make it happen. How to measure the rendered DOM in headless Chromium and refuse to rasterize any composition that breaks the layout contract."
+---
+
+## Shipped
+
+devlog v0.9.0 gave cover generation two things: a 20-icon SVG catalog for small accent glyphs, and a fixed hero zone, a 1300x400 box every cover's illustration must occupy. The interesting part is the enforcement. The renderer now measures the composed page in headless Chromium and throws before taking the screenshot if the hero zone is missing, misplaced, or has a catalog icon drifting into it. This post is about that pattern: when an agent composes visual output, put the layout rules in a geometry check, not just in the prompt.
+
+## Why prose rules weren't enough
+
+My covers are HTML/SVG documents composed by an agent from a style guide, then rasterized to PNG. The style guide said things like "catalog icons are never the hero illustration." The old safeguard for that rule was a regex asserting the sentence still existed in the instructions. That checks the rule is *stated*; it says nothing about whether any given cover *follows* it. An agent could compose two catalog icons connected by a line, call that the hero, and nothing mechanical would object.
+
+The fix is to make the rule checkable in the artifact itself. Two conventions do the work:
+
+- The required region is an element with a well-known id, `#hero-zone`, at exact coordinates.
+- Every restricted element carries a machine-readable marker, a [`data-*` attribute](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) like `data-catalog-icon="git"`, so the checker can find them with a `[data-catalog-icon]` selector.
+
+Once the contract is addressable in the DOM, you can measure it.
+
+## Build the gate: rect math that can't be gamed
+
+Start with the contract and two helpers in `layout-gate.mjs`:
+
+```js
+// layout-gate.mjs
+// The fixed box the composition must place its illustration container in,
+// on a 1600x900 canvas. Single source of truth; the style guide states the
+// same numbers as prose.
+export const HERO_ZONE = { x: 150, y: 425, width: 1300, height: 400 };
+
+// getBoundingClientRect() returns DOMRect values typed as unrestricted
+// double, so subpixel results are legal; exact equality would flake.
+// 2px absorbs rounding without becoming a real size allowance.
+const TOLERANCE_PX = 2;
+
+// Exact-match within tolerance, NOT containment. A containment check is
+// gameable: a tiny box in a corner is still "inside" the target, and a
+// tiny box trivially avoids overlapping anything.
+function withinTolerance(rect, fixed) {
+  return (
+    Math.abs(rect.x - fixed.x) <= TOLERANCE_PX &&
+    Math.abs(rect.y - fixed.y) <= TOLERANCE_PX &&
+    Math.abs(rect.width - fixed.width) <= TOLERANCE_PX &&
+    Math.abs(rect.height - fixed.height) <= TOLERANCE_PX
+  );
+}
+
+// Positive-area intersection only: rects that merely touch along an edge
+// do not count as overlapping.
+function rectsOverlap(a, b) {
+  const left = Math.max(a.x, b.x);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const top = Math.max(a.y, b.y);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return right > left && bottom > top;
+}
+```
+
+Then the check itself. It runs inside the page via [`page.evaluate`](https://playwright.dev/docs/evaluating), which executes the callback in the browser context and serializes the result back to Node; DOM rects have to be copied into plain objects on the browser side:
+
+```js
+// layout-gate.mjs (continued)
+export async function checkLayout(page) {
+  const zones = await page.evaluate(() =>
+    [...document.querySelectorAll('#hero-zone')].map((el) => {
+      const r = el.getBoundingClientRect();
+      return { x: r.x, y: r.y, width: r.width, height: r.height };
+    })
+  );
+
+  // Structurally mandatory: zero matches and duplicates are both errors,
+  // never "skip the check" or "take the first one."
+  if (zones.length === 0) throw new Error('layout gate: no #hero-zone element');
+  if (zones.length > 1) throw new Error(`layout gate: ${zones.length} #hero-zone elements`);
+
+  const zone = zones[0];
+  if (!withinTolerance(zone, HERO_ZONE)) {
+    throw new Error(
+      `layout gate: #hero-zone at x:${zone.x} y:${zone.y} ` +
+      `${zone.width}x${zone.height}, expected x:${HERO_ZONE.x} y:${HERO_ZONE.y} ` +
+      `${HERO_ZONE.width}x${HERO_ZONE.height}`
+    );
+  }
+
+  const icons = await page.evaluate(() =>
+    [...document.querySelectorAll('[data-catalog-icon]')].map((el) => {
+      const r = el.getBoundingClientRect();
+      return { name: el.getAttribute('data-catalog-icon'), x: r.x, y: r.y, width: r.width, height: r.height };
+    })
+  );
+
+  const offending = icons.filter((i) => rectsOverlap(i, zone)).map((i) => i.name);
+  if (offending.length > 0) {
+    throw new Error(`layout gate: catalog icons inside the hero zone: ${offending.join(', ')}`);
+  }
+}
+```
+
+The measurement is [`getBoundingClientRect`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect), which reports each element's rendered position and size in pixels relative to the viewport. That's the point of the whole design: you're checking what Chromium actually laid out, not what the markup claims.
+
+## Wire it in before the screenshot
+
+You need the full `playwright` package and a Chromium build (`npm i playwright && npx playwright install chromium`). The gate goes between page load and rasterization, so a bad composition fails loudly instead of producing a wrong image:
+
+```js
+// render.mjs
+import { chromium } from 'playwright';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { checkLayout } from './layout-gate.mjs';
+
+export async function render(htmlPath, outPath) {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage({ viewport: { width: 1600, height: 900 } });
+    await page.setContent(readFileSync(htmlPath, 'utf8'), { waitUntil: 'networkidle' });
+    await checkLayout(page); // throws on any contract violation
+    writeFileSync(outPath, await page.screenshot());
+  } finally {
+    await browser.close();
+  }
+}
+```
+
+In my pipeline the caller catches the throw, feeds the error text back to the agent for one recomposition attempt, and otherwise publishes without a cover. The gate's error messages carry the measured numbers for exactly that reason; "your box is at y:300, expected y:425" is a prompt the agent can act on.
+
+## Try it against a cheating layout
+
+Make one compliant page and one that breaks the contract:
+
+```html
+<!-- good.html -->
+<!DOCTYPE html>
+<html><head><style>html, body { margin: 0; width: 1600px; height: 900px; }</style></head>
+<body>
+  <div id="hero-zone" style="position:absolute; left:150px; top:425px; width:1300px; height:400px;"></div>
+</body></html>
+```
+
+```html
+<!-- cheat.html: tiny hero zone parked in a corner -->
+<!DOCTYPE html>
+<html><head><style>html, body { margin: 0; width: 1600px; height: 900px; }</style></head>
+<body>
+  <div id="hero-zone" style="position:absolute; left:20px; top:20px; width:80px; height:60px;"></div>
+</body></html>
+```
+
+Run both:
+
+```js
+// verify.mjs
+import { render } from './render.mjs';
+
+await render('good.html', 'good.png');
+console.log('good.html rendered');
+try {
+  await render('cheat.html', 'cheat.png');
+} catch (e) {
+  console.log('cheat.html rejected:', e.message);
+}
+```
+
+Output from my run of these exact files:
+
+```text
+good.html rendered
+cheat.html rejected: layout gate: #hero-zone at x:20 y:20 80x60, expected x:150 y:425 1300x400
+```
+
+Add a `data-catalog-icon` element inside the zone to `good.html` and it flips to the overlap error, naming the icon.
+
+## Gotchas
+
+- **Containment instead of exact-match.** The tempting check is "is the zone inside the canvas region." Symptom: covers pass the gate with a postage-stamp hero zone, because a tiny box is contained by anything and overlaps nothing. Escape: compare all four rect values against the fixed contract, within tolerance; the `cheat.html` run above is the regression test.
+- **Exact equality on measured pixels.** DOMRect fields are `unrestricted double` per the [geometry spec](https://drafts.csswg.org/geometry/), so layout can hand you 424.996 for your 425. Symptom: the gate rejects visually perfect compositions intermittently. Escape: a small absolute tolerance (2px here); keep it small enough that it never becomes a design allowance.
+- **The gate validates the box, not what's in it.** This one bit me a day after shipping: a cover can place `#hero-zone` perfectly and still strand a thin band of marks in a mostly-empty rectangle, passing every mechanical check while failing as an image. The v0.10.0 style guide added an explicit fill floor for exactly this reason. Escape: know which rules are geometry (checkable here) and which are composition quality; the latter need a different gate, or eyes.
+- **Duplicate ids fail open if you use `querySelector`.** `querySelector('#hero-zone')` silently returns the first match, so a stray second zone would be invisible to the check. Symptom: none, which is the problem. Escape: `querySelectorAll` and treat any count other than one as an error.
+
+## Sources
+
+- [MDN: Element.getBoundingClientRect()](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) — what the measured rect contains and that it reflects rendered position/size in pixels
+- [CSSWG Geometry Interfaces spec](https://drafts.csswg.org/geometry/) — DOMRect fields are `unrestricted double`, so subpixel values are legal
+- [Playwright: Evaluating JavaScript](https://playwright.dev/docs/evaluating) — `page.evaluate` runs in the browser context and serializes results back
+- [MDN: Using data attributes](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Solve_HTML_problems/Use_data_attributes) — marking restricted elements so a checker can select them
+
+## Changelog
+
+- feat(devlog): icon catalog + geometry-enforced hero zone for cover quality (v0.9.0) ([8848307](https://github.com/natejswenson/claude-skills/commit/8848307e00d37e0a76d1a3a3a77f7d360e8ed7ff))

package/evals/baseline/published/ghostwriter-v0.11.0.md

@@ -0,0 +1,211 @@
+---
+title: "Catching layout bugs before your eyes do: a render-time QA gate for generated visuals"
+date: 2026-07-18
+project: ghostwriter
+version: v0.11.0
+tags: [playwright, css, has-selector, visual-regression-testing, dom-testing, browser-automation, generative-content, layout-qa]
+summary: "How to measure a rendered HTML page for overflow and truncation before a human ever sees it, and the CSS trick that lets one layout adapt itself to however much content lands in it."
+---
+
+## Shipped
+
+I maintain a skill that turns a handful of bullet points into a LinkedIn-ready image: an HTML/CSS template gets filled in and rendered to a PNG through a headless browser. The same release also added a publish log and a self-repairing scheduler for a separate part of that skill, but the fix worth teaching is what happened to the card renderer. An 11-agent audit across all 13 card templates at sparse, typical, and stress content volumes turned up 40 first-render defects, 21 of them severe: clipped headlines, ellipses firing where nobody wanted truncation, dead bands of empty space. The root cause was simple: every template had been eyeballed with one content shape in mind, and nothing ever measured what rendered. The fix was a lint that runs at render time and asserts on the live DOM, paired with CSS that adapts a layout's proportions to whatever content count it's actually carrying. That combination is the technique this post walks through, generalized so it works on any HTML-to-image pipeline, not just mine.
+
+## Why reviewing the template isn't enough
+
+A card template looks fine in the editor because you're reading markup, not a render. The moment real content lands in it, the browser does layout math you didn't picture: a 40-character title becomes 60 characters and now it wraps to a third line, a 3-step list becomes a 7-step list and now something is 30 pixels below the fold. Functional and unit tests don't see any of this, because they check behavior, not what a browser painted onto a page ([Percy](https://percy.io/blog/visual-regression-testing/)). If nothing measures the rendered box model, a broken card reaches a human for the first time when it's already about to ship.
+
+The fix is to treat the render itself as a test subject: load the real page in a real browser, measure the elements that matter, and fail loudly before a screenshot goes anywhere.
+
+## Build a card that has to survive variable content
+
+Here's a stripped-down version of the pattern (not the production template, just the shape of it): a fixed-size frame holding a variable number of "step" blocks, each with a title and a detail line.
+
+```css
+/* style.css */
+#canvas {
+  width: 800px;
+  height: 500px;
+  padding: 40px;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 20px;
+  background: #10141c;
+  font-family: -apple-system, sans-serif;
+  overflow: hidden; /* content that doesn't fit gets clipped, not reflowed */
+}
+.step { display: flex; flex-direction: column; gap: 4px; }
+.step .title {
+  color: #fff;
+  font-size: 32px;
+  font-weight: 700;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.step .detail { color: #9aa4b2; font-size: 20px; }
+```
+
+```python
+# make_card.py
+import sys
+from pathlib import Path
+
+CSS = Path(__file__).parent / "style.css"
+TEMPLATE = """<!DOCTYPE html>
+<html><head><style>{css}</style></head>
+<body><div id="canvas">{steps}</div></body></html>"""
+STEP = """<div class="step"><div class="title">{title}</div><div class="detail">{detail}</div></div>"""
+
+
+def build(steps: list[tuple[str, str]]) -> str:
+    css = CSS.read_text()
+    body = "\n".join(STEP.format(title=t, detail=d) for t, d in steps)
+    return TEMPLATE.format(css=css, steps=body)
+
+
+if __name__ == "__main__":
+    out = Path(sys.argv[1])
+    steps = [
+        ("Clone the repo", "git clone the project"),
+        ("Install deps", "pip install -r requirements.txt"),
+        ("Run the build", "make build"),
+    ]
+    out.write_text(build(steps))
+    print(f"wrote {out}")
+```
+
+A fixed 800x500 frame with a variable list dropped into it is exactly the shape that breaks: it looks great with three steps and quietly overflows with seven.
+
+## Give the layout room to adapt
+
+Rather than pick one font size and hope every future caller respects it, let the CSS itself react to how many `.step` elements showed up. The `:has()` relational pseudo-class matches an element based on what's inside it, so a container can style itself differently depending on its own children ([MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/:has)):
+
+```css
+/* count-adaptive: exactly 3 steps get more room to breathe */
+#canvas:has(> .step:nth-child(3):last-child) { gap: 36px; }
+#canvas:has(> .step:nth-child(3):last-child) .title { font-size: 40px; }
+
+/* count-adaptive: 5 or more steps compress to keep everything on-frame */
+#canvas:has(> .step:nth-child(5)) { gap: 10px; }
+#canvas:has(> .step:nth-child(5)) .title { font-size: 24px; }
+#canvas:has(> .step:nth-child(5)) .detail { font-size: 16px; }
+```
+
+A sparse 3-step card scales up and fills the frame instead of floating in whitespace; a dense 5+ step card compresses to stay on-frame instead of overflowing. One template, no per-caller tuning.
+
+## Build the render-time lint
+
+The CSS above narrows the failure modes, but it doesn't guarantee anything, so the lint is what verifies a given render. It loads the page in Playwright and reads real box-model numbers off the live DOM with `page.evaluate` ([Playwright docs](https://playwright.dev/docs/api/class-locator#locator-bounding-box)):
+
+```python
+# lint.py
+import sys
+from playwright.sync_api import sync_playwright
+
+STEP_BUDGET = (3, 5)  # inclusive min/max steps a card is allowed to carry
+
+LINT_JS = """
+() => {
+  const findings = [];
+  const canvas = document.getElementById('canvas');
+  const cRect = canvas.getBoundingClientRect();
+
+  // 1. clip-overflow: anything escaping the frame.
+  for (const el of canvas.querySelectorAll('*')) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    if (r.bottom > cRect.bottom + 1 || r.right > cRect.right + 1) {
+      findings.push(['FAIL', 'clip-overflow',
+        el.className + ' extends past the frame (bottom ' + Math.round(r.bottom) +
+        'px vs frame ' + Math.round(cRect.bottom) + 'px)']);
+    }
+  }
+
+  // 2. ellipsis-fired: truncation actually happened.
+  for (const el of canvas.querySelectorAll('.title')) {
+    if (el.scrollWidth > el.clientWidth + 1) {
+      findings.push(['FAIL', 'ellipsis-fired',
+        '"' + el.textContent + '" is truncated (' + el.scrollWidth + 'px of text in ' +
+        el.clientWidth + 'px)']);
+    }
+  }
+
+  findings.push(['INFO', 'step-count', canvas.querySelectorAll('.step').length + ' steps']);
+  return findings;
+}
+"""
+
+
+def lint(html_path: str) -> list[tuple[str, str, str]]:
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page(viewport={"width": 900, "height": 600})
+        page.goto(f"file://{html_path}")
+        findings = page.evaluate(LINT_JS)
+        browser.close()
+
+    lo, hi = STEP_BUDGET
+    count = next(int(m.split()[0]) for (_, code, m) in findings if code == "step-count")
+    if not (lo <= count <= hi):
+        findings.append(("FAIL", "count-budget", f"{count} steps, budget is {lo}-{hi}"))
+    return findings
+
+
+if __name__ == "__main__":
+    findings = lint(sys.argv[1])
+    for level, code, message in findings:
+        print(f"{level} {code}: {message}")
+    sys.exit(2 if any(level == "FAIL" for level, _, _ in findings) else 0)
+```
+
+The `scrollWidth > clientWidth` check is the standard way to prove an ellipsis fired rather than just being legal CSS that never triggers: `scrollWidth` is how wide the content would need to be to show it all, `clientWidth` is what it got ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollWidth)).
+
+## Run it against a good, a sparse, and a stressed card
+
+A 3-step card renders and lints clean:
+
+```text
+$ python make_card.py good.html && python lint.py good.html
+wrote good.html
+INFO step-count: 3 steps
+```
+
+Edit the `steps` list in `make_card.py` down to 2 entries and rerun the same two commands. The count budget catches it before anyone has to notice the card looks thin:
+
+```text
+INFO step-count: 2 steps
+FAIL count-budget: 2 steps, budget is 3-5
+```
+
+Grow the list back out to 7 entries, with one title long enough to overflow ("Configure the deeply nested production environment variable file"), and the lint catches the truncation directly, quoting the exact text that got cut:
+
+```text
+FAIL ellipsis-fired: "Configure the deeply nested production environment variable file" is truncated (744px of text in 720px)
+INFO step-count: 7 steps
+FAIL count-budget: 7 steps, budget is 3-5
+```
+
+Every one of those lines is something a human would otherwise have had to spot by squinting at a PNG.
+
+## Gotchas
+
+**`:has(> .step:nth-child(3))` without `:last-child` fires on every card with 3 or more steps, not exactly 3.** `nth-child(3)` only asserts that a 3rd child exists; it says nothing about whether a 4th or 5th one follows. I proved this to myself in a scratch page: a 5-step card with the anchor-less rule still painted its 3rd title red, because the 5-step card also has a 3rd child. Anchoring with `:nth-child(3):last-child` is the fix: it means "exactly 3, and that one is the last."
+
+**A lint that can crash your render pipeline is worse than no lint.** The moment render-time checks run inside the same process that produces the shippable output, a bug in the lint itself (a null element, an unexpected DOM shape) can take down every render, not just the bad ones. Wrap the lint call so a lint exception degrades to a logged warning, never a failed render; the checks should only ever add information, not a new way to go down.
+
+**Count-adaptive rules fix font size and spacing, not structural imbalance.** Scaling text up or down for 3 versus 5 items works fine until the count lands somewhere a grid can't distribute evenly, like exactly 3 tiles in a 2-column layout: one tile ends up alone on its own row, off-center. That case needs an explicit structural rule (span the odd tile across the full row), not just a smaller font. Count-adaptive CSS has to cover both the aesthetic scaling and the structural edge cases, or the "edge count" just moves somewhere new.
+
+## Sources
+
+- [MDN: :has()](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) — the relational pseudo-class semantics and combinator syntax used for count-adaptive rules
+- [Playwright: Locator.boundingBox()](https://playwright.dev/docs/api/class-locator#locator-bounding-box) — measuring live DOM geometry from inside a headless browser
+- [MDN: Element.scrollWidth](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollWidth) — the scrollWidth/clientWidth comparison used to detect a fired ellipsis
+- [Percy: What is visual regression testing?](https://percy.io/blog/visual-regression-testing/) — why appearance bugs slip past tests that only check behavior
+
+## Changelog
+
+- feat(ghostwriter): graphics quality overhaul — render-time lint, count-adaptive cards, content-budget contract (#76) ([682884a](https://github.com/natejswenson/claude-skills/commit/682884a4fa8c624a467467978ae32ef70c3d56b1))
+- feat(ghostwriter): v0.11.0 — outcome feedback loop, self-repairing radar, in-session UX (#75) ([eeae226](https://github.com/natejswenson/claude-skills/commit/eeae2260c4c97f944c778001fa5c8d309f635669))