Decision artifact2026-08-15Session framework · 👯🤖 blocklist

The blockers list — work only your hands can do

Last night surfaced a recurring category no existing lane holds: fixes that are fully specified — the exact line, the exact click — where the only missing ingredient is your keyboard, your account, or your device. They are not RCs (nothing to release) and not decisions (nothing to decide), so today they land in scratchpads and close-out reports and are never surfaced again. You asked for a plan for a formal, local-only list, security first. This page makes four calls: the scope test (BL1), where the list lives and how it stays off the public site (BL2), how an agent writes to it in ten seconds (BL3), and how it actually reaches you (BL4) — plus a threat model taken seriously without melodrama, and a seed inventory written tonight (locally, never here).

Calls BL1–BL4 Seed 6 open · 3 resolved · 3 near-miss (local only) Storage rec workspace-local file + sentinel + deploy guard Status Decided 2026-08-15 — all four adopted

Decisions

Decided

@jwildfire · 2026-08-15 · in chat

“BL1-4 look good. Recommendations approved.”

All four calls adopted as recommended: the scope test stands as written (BL1); the list lives in the workspace-local file outside every repo, with the sentinel, the deploy-time guard, and the hub gitignore line (BL2); agents capture through a ten-second blocker-log script (BL3); full text stays on local surfaces only — published pages carry a count at most (BL4).

Implemented same day: the deploy guard and gitignore line landed in this repo's deploy workflow; the blocker-log capture script landed in the agent-tooling repo; the seed file, already live at the recommended location, was promoted from provisional to canonical. The read path — the dashboard's “your hands” section and the walkthrough skill — is filed as follow-up work in the agent-tooling repo, and the count-line spec goes to the daily-briefing design rather than being built in parallel.

The situation

Three sentences

Agents in this program regularly hit walls that only @jwildfire can clear — settings files the permission classifier refuses to let an agent write, account-level grants, interactive logins — and the current record of those walls is scattered across scratchpad close-outs, memory files, and issue comments, where tonight's evidence shows they accumulate silently: one such item sat sixteen days after it was already fixed, and three live ones from the last 24 hours are surfaced nowhere he would see them. Such a list is inherently sensitive — it names exactly which security controls stop agents from acting and where the boundaries are soft, and the hub's deploy workflow publishes reports/ wholesale to a public site, so "just keep it in the repo" is a concrete leak path, not a hypothetical. This artifact proposes the list's scope, home, write path, and read path; nothing is built until you answer, and the live seed inventory was written to the proposed local file only — this page describes categories, never the map itself.

"I also wonder if we need a formal 'blockers' list for things that don't fit into RC or Decision artifacts. That list might be local only since it's going to be my hands on keyboard to implement. Work on a plan for that too - security probably important for that one …" — @jwildfire, 2026-08-15

BL1 · What belongs on it

The test, in one sentence

Proposed rule

An item is a blocker only if the fix is fully specified and the sole missing ingredient is your physical access — keyboard, account, or device.

The counter-test catches everything else: if a one-word "yes" from you would let an agent do it, it is not a blocker — it is an approval ask or a decision. Blockers are known answers waiting on hands; decisions are unknown answers waiting on judgment; RCs are finished work waiting on review; everything else is an issue an agent can pick up.

Routing table

The thing in hand	Lane	Why
Fix known, agent classifier-blocked or physically unable	Blockers list	Only his hands are missing
Answer unknown; options need weighing	Decision artifact + Q&A	His judgment is missing, not his hands
Finished work proposed for release	RC PR / draft release	The review queue's only tenant
Agent-doable work, now or later	Ordinary issue	Milestone it and pick it up
Agent-doable the moment he approves	Approval ask	Fails the counter-test — a "yes" clears it

Worked examples from the last 24 hours

Blockers (all real, all in tonight's seed): a one-line permission-allowlist addition to a workspace settings file agents are classifier-blocked from writing; a harness-instructions block with workspace-wide effect that the agent flagged rather than guessed; a repo-level settings file whose absence forces every hub write through workarounds; an org SSO authorisation; a device-side list the Siri capture lane polls for.
Resolved same-category items, kept as lifecycle evidence: a startup setting in his user config (verified done tonight — it cleared within a day of being surfaced); a merge-tool allowlist line (recommended in a public artifact, landed within hours); a GitHub App install that was done on 07-29 but whose "still blocked" record survived sixteen days — the case for verified-dates on every entry.
Near-misses that look like blockers but are not: deleting an unmerged worktree and a stray branch — feels like "only Jeremy can", but an agent executes the moment he says yes → approval ask; a missing CI workflow flagged as "a precondition on him" — the workflow file was agent-writable and an agent wrote it the same night → ordinary issue; a framework-wording contradiction — nothing to type, something to decide → decision lane.

Threat model

What the list leaks, to whom, and what it actually costs

The list is, by construction, a map of the trust boundary: which settings are gated, which grants are missing, which controls have soft edges. Three adversaries, in descending order of realism:

A mechanical sweep — the proven one. The hub deploy workflow runs cp -r reports _site/reports and triggers on any push touching reports/**: anything placed under reports/ is on the public site within minutes, no human in the loop. A second live lane: the session wrapup folds the scratchpad into the published diary — so blockers captured in scratchpads today are already one fold away from public. The status quo is leakier than any option on this page.
An opportunistic reader of the public site. What they'd learn: the automation's constraint map — which files agents can't write, which tokens lack which scopes. What they could do with it: reconnaissance convenience, nothing more — the list contains no credentials, and the individually-public issue trail already discloses much of it piecemeal. The aggregation is what's new and worth withholding; this is a personal workspace, not a bank, and the proportionate response is placement and a tripwire, not encryption.
Your own tooling and future agents. A future agent with a broad glob, a usage-report generator, a diary fold — none malicious, all mechanical. Defences must therefore survive an agent copying the content somewhere swept, which placement alone cannot; that is what the sentinel-plus-guard below is for.

The concrete failure mode

Discipline alone fails here because the leak path is automated: one well-meaning cp into reports/, or one scratchpad fold, publishes the map with zero further human action. Every layer below assumes agents will eventually make exactly that mistake.

BL2 · Where it lives

Five homes, priced honestly

Evaluated on: who can read it, what happens on a careless git add -A, whether the deploy sweep can reach it, whether agents can append cheaply, and whether it survives machine loss.

(a) A file at the workspace root: `~/Documents/obot2/.claude/blockers.md`

Recommended

Who reads: Any local agent — which is fine: agents already know the walls (they hit them); the threat is publication, not local reads.
git add -A: Structurally immune. The workspace root is not a git repository — there is no repo for any git add to run in, which is strictly stronger than a gitignore entry.
Deploy sweep: Immune by location (the workflow copies obot.roadmap/reports/ only). The copy failure mode is covered by the sentinel + guard below.
Agent append: Trivial — same directory as the session scratchpads every agent already writes; same script pattern as scratchpad-log.
Machine loss: Lost — accepted: every entry is re-derivable from its cited source (issue, artifact, close-out), and the daily count (BL4) means a vanished list is noticed, not silent. If the list ever becomes load-bearing history, option (b) is the upgrade path.

(b) A file in a private repo

Not now

Who reads: You + agents with the token; GitHub, Inc. holds the map.
git add -A: Committing is the point — but one repo-visibility flip, or one agent quoting the file into a public artifact, publishes everything at once.
Cost: No private repo exists in the portfolio today: creating one, installing the app, and teaching every agent a second remote adds real ceremony to what must be a ten-second capture. Survives machine loss — the one genuine advantage.

(c) The agent-memory directory

Wrong tool

Why not: Memories are designed to be recalled into every session's context and paraphrased into outputs — including published ones; that is the opposite of containment. Multi-writer semantics are poor, there is no check-off lifecycle, and a queue is not a memory. Tonight's sixteen-day-stale "still blocked" memory line is the standing exhibit.

(d) A file under `~/.claude/`

Close second, loses on discoverability

Why not: Identical safety to (a) — outside every repo — but outside the workspace agents grep and outside the scratchpad conventions they already follow; it splits program state across two roots for zero added protection.

(e) Labelled issues in a private repo

Best surfacing, worst capture

Why not: The strongest read path (phone, notifications) and the answer to "is a separate list even right?" — considered seriously. But it needs the private repo (b)'s costs plus per-item issue ceremony, and cross-referencing public threads from private issues either leaks titles into timelines or forces agents to keep two disciplines. If BL4's read path fails in practice, this is the first alternative to revisit — the analysis says the list is right and the file form is right for v1, not forever.

Recommendation — BL2

Option (a), wrapped in four defence layers, ordered by strength: location → sentinel → deploy guard → gitignore.

1. Location: outside every repo, so no git operation and no deploy can reach it. 2. Sentinel: the file opens with a fixed local-only marker comment, so any copy of its content is self-identifying. 3. Deploy-time guard: one step in the hub's deploy workflow, after site assembly — grep -rqF "$SENTINEL" _site && exit 1, where the workflow composes the marker string from two halves rather than spelling it out, so that pages documenting the guard (this one included) can never trip it. That is the merge-gate-guard prose-false-positive lesson (oa#58) applied in advance — and not hypothetically: this artifact's own pre-push check fired on its first draft, which quoted the sentinel verbatim. 4. Belt-and-braces: a blockers* line in the hub's .gitignore for the copy-the-file case. Layers 2–3 are the ones that survive agent error, which is the failure mode that actually occurs.

BL3 · How agents write it

Ten-second capture, or it won't happen

The capture moment is mid-task, at the exact instant an agent hits a wall — any friction and the item dies in a close-out paragraph instead. The proven pattern is scratchpad-log: one allowlisted script call, shelled timestamp, append-only, multi-writer safe. Proposed:

obot.agent/tools/blocker-log '<what>' --fix '<paste-ready command or diff>' --source '<url>'

Entry schema: one checkbox line per item — filed-date, verified-date, what, a paste-ready fix, source link, what unblocks. The verified-date is load-bearing: the sixteen-day-stale item survived precisely because nothing forced a re-check; the read path (BL4) re-verifies before surfacing and the script stamps verification at capture.
Dedup: the script greps for the item before appending — tonight two of four "unfiled blockers" turned out to be already filed elsewhere; the same failure mode applies here.
Lifecycle: resolved items move to a Resolved section with a date — never deleted (house rule) — and near-misses get routed to their correct lane at capture time by the BL1 counter-test, which the script's help text carries.
A thin skill wrapper later, script first: scripts work everywhere — siblings, ultracode jobs, hooks — where skills need a session; this mirrors how scratchpad-log shipped. (Ironic footnote, logged as evidence: the script's own allowlist line will be an early entry on the list it writes to.)

BL4 · How it reaches you

The part that decides whether any of this works

Tonight's evidence is blunt: items deferred to you accumulate silently and are never surfaced again — the ones that cleared (the startup setting, the merge allowlist) cleared because a page you actually read put them in front of you, within hours. So the read path is designed around moments you are already looking, plus one deliberate sit-down mode:

The session dashboard (local page) gets a "🔑 Your hands" section rendering the full list — it is served locally in Chrome, never published, so full item text is safe there.
A /session-blockers walkthrough, modelled on session-reviews: when you give it ten minutes, it re-verifies each item live, hands you one at a time with the exact paste-ready command, and marks done / defer / retire. This is the mechanism that actually drains the list — items carry their fix, so clearing three is minutes, not research.
The daily briefing carries a count only — never item text. The briefing is a published page. Proposed line: "🔑 3 items need your hands (~5 min) — run /session-blockers". This is handed to the briefing design already in flight (Q&A #158, M3) as a section spec, explicitly not a competing surface; if M3 lands, the blockers count is one of its nine lines.
🎩🤖 prime answers "what needs my hands?" from the file directly, and its rehydrate bundle carries the count so the answer is warm.

Recommendation — BL4

Full text on local surfaces only; published surfaces carry counts, never contents — as a hard rule, not a habit.

Adopt the dashboard section + /session-blockers walkthrough, hand the count-line spec to #158's briefing rather than building anything parallel, and treat "count-only on public pages" as the same class of rule as "no writes outside the jwildfire org".

The seed

Seeded tonight — described here, enumerated only locally

The proposed file was written tonight at the recommended location, sentinel first, so the list opens with real contents rather than an empty framework: 6 open items (two permission-allowlist/settings additions, one harness-instructions block, one repo-settings file, one org SSO authorisation, one device-side setup — plus one flagged verify-first: a 403 that may prove agent-doable on the user-token lane and would then retire itself), 3 resolved items kept as lifecycle evidence that this category clears fast once surfaced, and 3 near-misses recorded with the lane they were routed to instead. Each open entry carries a paste-ready fix, its source, and a verified-date checked against live state tonight — not copied from memory, which is how one of them was sixteen days wrong. Per this page's own threat model, the live inventory does not appear here; if BL2 lands somewhere other than the proposed file, the seed moves with it.

What unblocks

On each answer

Adopt all (the default) — one agent increment builds the rest: blocker-log, the deploy-time guard step in the hub workflow, the hub gitignore line, the dashboard section, and the /session-blockers skill; the count-line spec goes to #158. The seed is already live, so the list works from day one.
BL2 ≠ (a) — the seed file moves to your chosen home; the sentinel and guard survive every option except (e), which replaces them with issue discipline.
BL1 amended — the test's wording is yours to sharpen; the routing table and near-miss rule adjust to match.
Reject the list outright — the six open items still exist and still need your hands; they would be re-homed as comments on their source issues plus a standing section in the wrapup, which is the leakier and quieter status quo this page argues against.

Answer in Q&A discussion #162 — "adopt all" is a complete answer.