blackboard

Record and retrieve contemporaneous findings in the repository journal.

SKILL.md

GitHub

Session journal

Read applicable AGENTS.md and their declared adapter alias, otherwise .agents/skills/blackboard/SKILL.md from the repository root if present. Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.

Use when the current repository provides a journal, blackboard, or equivalent durable session record. Read local AGENTS.md for the provider, credential, retention, and subagent-identity rules.

Journal operations are tools of the vouchington-tooling MCP server (vouchington mcp): journal_append, journal_entries, outbox_status, outbox_flush, session_ensure, snapshot_export, and session_archive. Harnesses name them differently, so match the bare tool name: mcp__vouchington-tooling__<tool>, mcp__vouchington_tooling__<tool> (the hyphen becomes an underscore), or vouchington-tooling__<tool> reached through a search_tool and use_tool pair, or the vouchington-tooling namespace reached through GetDynamicTools and CallDynamicTool. Every call takes an exact sessionId, never inferred, whose meaning depends on the tool:

  • journal_append and session_ensure: the session written or ensured, which is the caller's own session unless a runner ensures a child identity.
  • journal_entries and session_archive: the session read or archived, which during distillation belongs to another agent.
  • snapshot_export, outbox_status, and outbox_flush: only the caller. The outbox is per worktree, so outbox_status and outbox_flush report two counts: pendingCount is the unsent records of that sessionId, and worktreePendingCount is the unsent records of every session in the worktree outbox. outbox_flush delivers every retained record in the worktree. A permanently rejected record (identity-conflict, event-conflict, archived-session) is moved out of the pending set, not retained: rejectedCount and worktreeRejectedCount count the kept copies, outbox_flush reports them as rejected (sourceEventId and diagnostic), and a corrected retry with the same sourceEventId is accepted.

Every call may take worktree, the absolute path of a worktree of the current repository (the launch worktree by default). Writing or retrying an entry needs no provider skill, temporary file, --file flag, or replay command. Search for journal_append (by bare name, so every prefix matches) before concluding the server is unavailable; a deferred harness lists the tool only on request. A tool error is not unavailability: act on its message and retry through MCP.

When the server is unavailable

MCP is the supported journaling path. If the search finds no such tool, stop journaling and tell the human which case applies before continuing:

  • Not registered: the machine's agent configuration must register it; follow the consumer's registration and diagnosis steps.
  • Registered but disconnected: reconnect it through the harness's MCP controls, or restart the harness.
  • Automated runs with no human to ask: an unattended interactive run continues its primary work, while an autonomous run keeps its admission gate below. The final report states why journaling was unavailable, the pendingCount and worktreePendingCount (or that none was written), and each unjournaled finding.

Harness sandboxes commonly withhold AGENT_BLACKBOARD_TOKEN from shell commands. Never request an unsandboxed run only to obtain the token, and do not treat a permission denial as tool unavailability or bypass a host approval requirement. If MCP cannot persist the note, stop and report the blocker.

Journaling policy

  1. Friction is the primary thing to journal: failed or recovered checks, denied or approved permissions, scope changes, repeated fixes, and reusable tool gaps. Capture it before filing an issue. Broader consequential observations, such as first-party tool behavior and architectural findings, are allowed but secondary: add them after the friction is recorded, never in place of it. A consumer wrapper may add repository-specific triggers but does not narrow this list. Record useful resolved outcomes as well as unresolved gaps. Include bounded evidence, affected areas, an explicit disposition, and an existing tracking reference when present. Journal meaningful skips or bypasses of applicable configured workflows before completion, with the owning workflow or command-catalog entrypoint, reason, and observed result/action.
  2. Record each observation with one journal_append call and pass the note as its markdown argument (at most 12000 bytes). Required arguments are sessionId, parentSessionId (null for a root session), agent, version, mode, markdown, a stable sourceEventId, workOutcome, canonical exact repositories, and explicit feedbackCoverage. Never pass a timestamp: the server owns it, rejects the argument, and returns the timestamp it used. Nothing is written unless the whole envelope validates. The tool writes journal entries; category is optional context and never changes storage type or distillation eligibility. Generate routine facts and metadata through the approved composer and pass its output as markdown instead of hand-authoring factual markers. journal_append stores only journal entries: save a composed retrospective through the retrospective skill's writer, never through journal_append.
  3. Preserve exact provider session and parent identities. Each agent writes only its own session. journal_append ensures that session and merges the entry's repositories into the session's cumulative repository union, so list every repository the entry concerns. Never infer another repository from prose or create a child identity from a model guess. Call session_ensure with the exact identity only when a runner must confirm the session before work starts. A session that already stores a different version still receives the entry, and the result reports its storedVersion. A different parentSessionId or agent is an identity-conflict whose error names each differing field with its stored and supplied values.
  4. Select the repository's trusted mode (interactive or autonomous) explicitly. In interactive mode an outage may retain the validated, sanitized record in the bounded durable outbox, and journal_append reports it as pending. Report pendingCount (this session's unsent records), and worktreePendingCount when other sessions' records are also unsent, from journal_append or outbox_status. Deliver with outbox_flush once the provider is reachable, and continue primary work only after persistence succeeds. A full, corrupt, or unwritable outbox blocks capture; never evict or silently discard an unsent record.
  5. Autonomous runners require online session_ensure, a fresh admission journal_append, and readback before launching an attempt. Give each attempt's admission entry a sourceEventId unique to that attempt: reusing an earlier one returns the earlier receipt, which does not prove a fresh write. Autonomous mode has no filesystem outbox, so a failed delivery is an error. Terminal reporting preserves work outcome separately from feedback coverage and delivery. A filesystem outbox never grants admission or acknowledged completion.
  6. Use at-least-once delivery with consumer deduplication by exact session/source identity. To retry a pending or failed append, repeat the identical journal_append call with the same sourceEventId and content. The server's timestamp is not part of an event's identity, so a retry of an event already stored or retained reports the stored timestamp, even after a restart or an outage. The same sourceEventId with different content is rejected as a conflict, so use a new sourceEventId for a changed note. A transport timeout can leave a late durable write; pending or blocked is never an acknowledged receipt.
  7. Read the session's entries oldest-first with journal_entries for retrospectives. It returns every entry with its envelope, including its type and repository tags, so a retrospective can find an existing retrospective and keep entry-level tags. Record explicit none-observed with inspected scope, or not-assessed/unavailable with reason, when evidence does not establish a finding. A permission request is not proof of approval or denial; localhost refusal is not proof of sandbox enforcement. Mark partial capture and dropped counts instead of reporting clean evidence.

Never search for, print, invent, or mint credentials. Durable entries and outbox records contain only bounded structured facts or sanitized summaries, never raw command output, transcript content, environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.

Sandbox and permission blocks

A denied or escalated command uses this block grammar, one block per entry, because a retrospective's sandbox and permission audit is built only from entries that match it:

- `sandbox-escalation` — <command and subcommand only: no paths, hosts, branches, or secrets> — <what needed elevated access>
  - Outcome: requested|approved|denied|unknown
  - Evidence: <sanitized denial or approval text>
  - Disposition: <allowlist change, issue #N, or none>

Use sandbox-failure (a sandbox refusal) or ambiguous-failure (a failure whose cause is unclear) in place of sandbox-escalation for a command that failed without an escalation; those blocks omit the Outcome line. Set Outcome only from observed evidence: a request is requested, never approved. Always journal the block: the audit section is built from journal blocks alone, so an escalation reported only in the transcript facts leaves it saying none observed. The transcript's escalations are supplementary evidence under the transcript facts, not a substitute.

Credential failures

  • Never search shell profiles, env, or .env* files for a credential. Check presence only with [ -n "${VAR+x}" ] && echo SET || echo UNSET; never copy the token around a sandbox denial.
  • A missing or stale credential blocks hosted delivery. In interactive mode the outbox keeps the record visibly pending: do not drop it or invent a fallback. Ask the human to refresh the connection, then restart the MCP client or call outbox_flush; an automated run reports.

Child identity for spawned agents

  • Pass the parent's own session id in the assignment prompt. The child resolves its own id from its runtime through the consumer's identity policy, then calls session_ensure with it, the given parentSessionId, its agent, and its version before other work. With no id or a failed ensure, it stops and reports the blocker; never guess an id or pass a path, URL, or synthesized value.
  • A subagent sharing its parent's id must not session_ensure it as a child. It asks the parent to append, or skips this protocol.

Consumer wrappers own service configuration, server registration and approval rules, trusted mode selection, issue routing, and archival authorization. The server fixes the outbox location.