Jon Udell judell

TRACE × Bram — scoping the fit, with a working demo

Draft response to judell/bram#240 — "Tracing decisions made and by whom." Written up by Jon together with the Claude assistant inside Bram; fittingly, the provenance file in the demo below is a recording of that very session. @thru-echoes — curious what you make of this.

TL;DR

TRACE and Bram's worklist turn out to describe nearly the same thing from two directions. Bram is a workspace where an AI agent proposes a change, the human approves / drops / iterates, and it gets committed — and every step is already recorded. That's a decision-provenance stream by construction. So we did a small spike:

Read TRACE's data model and schemas/trace-v0.5.json.
Hand-authored a conforming trace-v0.5.json from a single real Bram session (today's).

Search-first triage: answering "should we do this?" from a searchable project history

A worked example from Bram. Produced by Bram's agent (Jon's Claude) from a real session, lightly edited for a blog post. The numbers are measured against this project's actual corpus.

The premise

Bram runs an AI coding agent alongside a worklist, and it indexes the whole project history — every Claude and Codex session transcript, every commit, every issue, and the worklist history — into an embedded SQLite FTS5 index, served at GET /__search.

The reason this matters is an economics problem. A single session transcript in this project runs 20–30 MB; the full transcript corpus is ~184M tokens. That is not something an agent can read or grep without destroying its context window. So before the index, the entire record of what the human and the agent had built together was effectively write-only to the agent. Ask it "have we hit this bug before?" or "didn't we already dec

Bram git / gh workflow patterns

Tabulated from three weeks of Claude Code session logs (2026-05-12 to 2026-06-02), Bram-driven.

Git: surgical operations Bram does on the user's behalf

bucket	what it covers
Hunk-level staging / unstaging	`-p` / `--patch` work: `add -p`, `checkout -p`, `restore -p`, `reset -p`, `stash push -p`. Plus `diff --cached` / `--staged` to review the staging area hunk by hunk.
Staging surgery (non-hunk)	`restore --staged <path>` to unstage a single file, `rm --cached`, `add --intent-to-add`, any `--index` / `--cached` flag work.

Reflections on the v0.1.31 process

v0.1.31 closed eight issues — #84, #85, #86, #88, #91, #92, #93, #94 — touching the spinner lifecycle, JSONL turn-end detection, the in-flight feedback panel, iframe-cascade cost, PTY click delivery, and permission-menu interaction. None of the fixes were guesses. Each followed the same loop: propose a worklist item carrying an explicit hypothesis and validation plan, approve into an apply cycle that itself acted as the test stimulus, grep the trace for the predicted signal, and either commit or iterate. Wrong hypotheses (lastAssistantText panel as the cascade driver; sessionTurns parsing as the bottleneck) were caught quickly because each proposal named the specific trace pattern that would confirm or refute it.

Instrumentation as a compounding asset

Each round added a single layer that survived into the codebase: helper-call per-call timing for JSONL-walking helpers, heartbeat-batch and talk-session-batch for aggregate main-thread health, jsonl-fanout for

Smoother upstream syncs for B-Square-Bulletin/community-calendar

Five commits just landed upstream that reduce merge friction for forks. Here's what to do and why.

What changed upstream

report.json and xmlui/version.txt are no longer tracked. These auto-generated files always diverge across forks, causing pointless merge conflicts.
xmlui/config.local.js is no longer tracked. It was already gitignored but still in the repo from an earlier commit. A config.local.js.example template is now shipped instead.

Event Rewriting for WFHB

WFHB needs to edit certain events as they flow from the community-calendar database to the iframed viewer. The approach: add an eventOverrides object to the existing excluded.json file that WFHB already manages in GitHub. The community-calendar viewer already fetches this file via the ?exclude= query param; it just needs to apply overrides in addition to exclusions.

Two repos are involved:

community-calendar (Jon) — the shared viewer that any city can iframe
wfhb (Chuck) — the WFHB-specific moderator UI

Part 1: community-calendar viewer (Jon)

The published blog at blog.xmlui.org is a standalone XMLUI app (xmlui-blog), separate from the main website. Its source lived in blog/src/ but has been removed from the working tree — only blog/dist/ remains.

The key file was blog/src/config.ts, which contains:

A hardcoded blogPosts array listing every post's metadata (title, slug, description, author, date, image, tags, draft).
That array is passed to the XMLUI runtime via appGlobals.blog.posts.
Blog markdown files are loaded from blog/public/blog/*.md via Vite glob import.
The Main.xmlui for the blog app used hardcoded Page routes with index-based references (posts[0], posts[1], etc.).

Adding a new post to the published blog requires:

	<!--
	B Square Bulletin — community calendar embed fix

	Problem: the current embed shows two scrollbars (page + iframe). The iframe
	has a fixed 1800px height with scrolling="yes", so when the event list is
	taller than 1800px it gets its own scrollbar inside the page's scrollbar,
	and when it's shorter you see a big gap.

	Fix: opt the iframe into auto-height mode (?autoheight=true), turn off its
	scrollbar, start it at height:0, and add a tiny postMessage listener that

	#!/usr/bin/env bash
	# verify_edge_functions.sh — compare deployed edge function source against repo
	#
	# Usage:
	# export SUPABASE_ACCESS_TOKEN=sbp_... # from supabase.com/dashboard/account/tokens
	# export SUPABASE_PROJECT_REF=your_project_ref
	# bash verify_edge_functions.sh
	#
	# Requires: curl, diff, jq
	# Run from the root of your community-calendar repo clone.

	-- Verify that a fork's Supabase database has all required objects.
	-- Paste this into the Supabase SQL Editor and run it.
	--
	-- Each check returns '✅ OK' or '❌ MISSING' with the fix.
	--
	-- Auto-generated from DDL files on 2026-04-24.
	-- Regenerate: python scripts/generate_verify_sql.py

	SELECT '── TABLES ──' AS section, '' AS status