vouchington-tooling 0.25.0 → 0.26.0

package/dist/mcp-server/context.d.mts

@@ -8,8 +8,7 @@ type ToolContext = {
     env: NodeJS.ProcessEnv;
     dependencies: BlackboardClientDependencies;
 };
-type ToolResult = string | Record<string, unknown>;
-export type ToolHandler = (args: Args, context: ToolContext) => Promise<ToolResult>;
+export type ToolHandler = (args: Args, context: ToolContext) => Promise<Record<string, unknown>>;
 /**
  * The consumer convention for the interactive outbox. It is derived, never accepted from the
  * caller, so a credentialed, unsandboxed server cannot be pointed at an arbitrary directory.

package/dist/mcp-server/dispatch.mjs

@@ -54,14 +54,7 @@ export async function callTool(name, rawArguments, environment) {
             // The client resolves from the validated worktree, never from the server's own location.
             dependencies: { ...environment.blackboard, resolveFrom: join(worktree, 'package.json') },
         });
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
-                },
-            ],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
     catch (error) {
         return { isError: true, content: [{ type: 'text', text: describeError(error) }] };

package/dist/mcp-server/fake-blackboard.test-helpers.d.mts

@@ -4,6 +4,7 @@ export declare const BLACKBOARD_ENV: {
     AGENT_BLACKBOARD_TOKEN: string;
 };
 type StoredEntry = {
+    sessionId?: string;
     createdAt: string;
     data: unknown;
 };

package/dist/mcp-server/handlers-journal.d.mts

@@ -1,5 +1,6 @@
 import { type ToolHandler } from './context.mts';
 export declare const journalAppend: ToolHandler;
+/** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
 export declare const journalEntries: ToolHandler;
 export declare const outboxStatus: ToolHandler;
 export declare const outboxFlush: ToolHandler;

package/dist/mcp-server/handlers-journal.mjs

@@ -1,4 +1,4 @@
-import { appendJournalMarkdown, feedbackOutboxStatus, flushFeedbackOutbox, formatJournalEntries, readJournal, } from '../agent-blackboard/index.mjs';
+import { appendJournalMarkdown, feedbackOutboxStatus, flushFeedbackOutbox, readJournal, } from '../agent-blackboard/index.mjs';
 import { optionalRecord, optionalString, requiredChoice, requiredString, requiredStringArray, rejectUnknown, } from './args.mjs';
 import { outboxDirectory, readIdentity } from './context.mjs';
 const MODES = ['interactive', 'autonomous'];
@@ -60,7 +60,24 @@ export const journalAppend = async (args, context) => {
     });
     return { sessionId: context.sessionId, timestamp, ...result };
 };
-export const journalEntries = async (_args, context) => formatJournalEntries(context.sessionId, await readJournal(context.sessionId, context.env, context.dependencies));
+// `Entries.get` documents no order, and `createdAt` is a service-generated ISO 8601 UTC time whose
+// text order is time order. An entry without a usable `createdAt` sorts first rather than throwing.
+function createdAtOf(entry) {
+    const createdAt = entry?.createdAt;
+    return typeof createdAt === 'string' ? createdAt : '';
+}
+function byCreatedAt(left, right) {
+    const leftAt = createdAtOf(left);
+    const rightAt = createdAtOf(right);
+    if (leftAt === rightAt)
+        return 0;
+    return leftAt < rightAt ? -1 : 1;
+}
+/** Every entry as the client returns it, oldest first. Nothing is filtered or rewritten. */
+export const journalEntries = async (_args, context) => ({
+    sessionId: context.sessionId,
+    entries: (await readJournal(context.sessionId, context.env, context.dependencies)).toSorted(byCreatedAt),
+});
 export const outboxStatus = async (_args, context) => ({
     sessionId: context.sessionId,
     ...feedbackOutboxStatus(outboxDirectory(context.worktree)),

package/dist/mcp-server/tools.mjs

@@ -97,7 +97,9 @@ export const TOOLS = [
         'repositories',
         'feedbackCoverage',
     ]),
-    tool('journal_entries', 'Returns the journal entries of one session, oldest first, as markdown.', READ_ONLY),
+    tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
+        'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
+        'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
     tool('outbox_status', 'Reports how many unsent journal records the worktree outbox retains. sessionId identifies ' +
         'the caller; the count covers the whole outbox.', READ_ONLY),
     tool('outbox_flush', 'Delivers retained outbox records and returns the remaining count. sessionId identifies the ' +

package/docs/mcp-server.md

@@ -45,7 +45,7 @@ as MCP tool errors (`isError: true`) with an actionable message rather than cras
 | Tool              | Arguments besides `sessionId` and `worktree`                                                                                                                                                    | Returns                                                                                         |
 | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
 | `journal_append`  | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `timestamp`, `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`) |
-| `journal_entries` | none                                                                                                                                                                                            | the session's entries as markdown                                                               |
+| `journal_entries` | none                                                                                                                                                                                            | `sessionId` and `entries`, every entry oldest first                                             |
 | `outbox_status`   | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`                                                           |
 | `outbox_flush`    | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`, `deliveredCount`                                         |
 | `session_ensure`  | `parentSessionId`, `agent`, `version`                                                                                                                                                           | `sessionId`, `status` (`created` or `exists`), `archived`                                       |
@@ -59,6 +59,13 @@ retrying the same `sourceEventId`, resend the same content and the `timestamp` t
 returned; the server fixes a default timestamp and returns it for that reason. Markdown is limited
 to 12000 bytes.
 
+`journal_entries` returns `{ sessionId, entries }`. Each entry is exactly what the `agent-blackboard`
+client returns (`sessionId`, `createdAt`, `data`), so `data` keeps its envelope fields such as
+`repositories`, `sourceEventId`, `workOutcome`, and `feedbackCoverage`. Entries of every type come
+back, including `retrospective` and legacy entries without an envelope. The client documents no
+order, so they are sorted stably by `createdAt`, oldest first. An empty session returns
+`entries: []`. `vouchington agent-blackboard journal entries` still prints journal markdown only.
+
 `sessionId` on `outbox_status`, `outbox_flush`, and `snapshot_export` only identifies the caller.
 The outbox is per worktree and the status and flush cover every record in it. Flushing an empty
 outbox does not create the directory. `snapshot_export` never accepts a destination: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/blackboard/SKILL.md

@@ -13,38 +13,75 @@ Use when the current repository provides a journal, blackboard, or equivalent du
 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`. A harness may prefix the tool names with the server name.
+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 tools cover
+  every record in the worktree outbox, not only that session's.
+
+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.
+If these tools are not available because the server is not registered or not connected, stop and
+report that the journal server is unavailable. Do not fall back to a CLI command.
+
 1. Capture consequential observations before filing an issue: failed or recovered checks, denied or
    approved permissions, repeated fixes, scope changes, first-party tool behavior, and architectural
    findings. 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. Use the shared validated envelope with storage `type: journal` or `retrospective`, canonical exact
-   entry repositories, stable `sourceEventId`, work outcome, and explicit feedback coverage. Category
-   is optional context; it never changes storage type or distillation eligibility. Generate routine
-   facts and metadata through the approved composer instead of hand-authoring factual markers.
+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`. Also pass an ISO 8601
+   `timestamp` fixed before the first attempt: the server otherwise generates one, and a failed or
+   timed-out call returns no result to learn it from. 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.
-   Update that session's cumulative repository union before appending; never infer another repository
-   from prose or create a child identity from a model guess.
-4. Select the repository's trusted mode explicitly. Interactive outages may retain validated,
-   sanitized feedback in the bounded durable outbox. Report pending count and delivery state, replay
-   with the same source identity, and continue primary work only after persistence succeeds. A full,
-   unsafe, or unwritable outbox blocks capture; never evict or silently discard an unsent record.
-5. Autonomous runners require online session ensure, a fresh admission write, and readback before
-   launching an attempt. 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. A
-   transport timeout can leave a late durable write; pending or blocked is never an acknowledged
-   receipt. Replay verifies matching content before retrying and rejects conflicting source reuse.
-7. Read journal entries oldest-first for retrospectives. 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.
+   `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.
+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 the pending count from `outbox_status`, deliver
+   with `outbox_flush` once the provider is reachable, and continue primary work only after
+   persistence succeeds. A full, unsafe, 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, call `journal_append` again with the same `sourceEventId`,
+   content, and `timestamp` from the first attempt: the whole envelope must match, and conflicting
+   source reuse is rejected. 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.
 
-Consumer wrappers own service configuration, trusted mode selection, commands, outbox location,
-issue routing, and archival authorization.
+Consumer wrappers own service configuration, server registration and approval rules, trusted mode
+selection, issue routing, and archival authorization. The server fixes the outbox location.

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": ["github-issue", "pr-description", "review-ci-logs"]
     },
@@ -18,13 +18,13 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -38,26 +38,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -70,26 +70,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -115,53 +115,53 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.10.0",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },

package/skills/retrospective-distill/SKILL.md

@@ -12,26 +12,48 @@ Local policy overrides these defaults; do not reload an already-read adapter or
 Use when completed retrospectives or journals should become durable follow-up work. Read local
 `AGENTS.md`, issue policy, and journal retention rules before any mutation.
 
-1. Enumerate only completed, eligible session records. For repository-scoped work, filter sessions
-   by repository membership and use only entries attributed to that repository. Leave untagged
-   legacy records unclassified. Do not infer their repository. Leave in-progress sessions intact.
-2. Validate storage type and the shared envelope independently of optional category. Never repair
+1. Enumerate only completed, eligible session records with the `snapshot_export` tool of the
+   `vouchington-tooling` MCP server, narrowing by `agent`, `version`, `parentSessionId`, exact
+   `data` fields, `dataArrayContains`, and `inactiveForHours`. It exports non-archived sessions to a
+   private local file and returns the path, counts, checksum, and manifest, never the records.
+   Before exporting, call `outbox_flush` and then `outbox_status` for every worktree that
+   `git worktree list` reports, passing each path as `worktree`, and stop if any still reports
+   pending records: an archived session refuses later delivery, so a retained record would never
+   be distilled. Outboxes in removed worktrees or on other machines cannot be drained this way, so
+   select with `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact.
+   If the server is not connected, stop and report it; do not fall back to a CLI command.
+2. Before using any record, verify the file against the returned checksum, counts, and terminal
+   manifest with the consumer's approved snapshot reader, and stop on a mismatch rather than
+   treating missing records as absent. Read full records, with their storage type, repository
+   tags, source identity, coverage, and outcomes, from that file. Do not distill from
+   `journal_entries`: it reads one session at a time and has no checksum or manifest to show that
+   the read is complete. For repository-scoped work, filter sessions by
+   repository membership (`dataArrayContains` with `repositories` and the exact `owner/name`) and
+   use only entries attributed to that repository. Leave untagged legacy records unclassified. Do
+   not infer their repository.
+3. Validate storage type and the shared envelope independently of optional category. Never repair
    unknown legacy types or repository provenance by inference. Quarantine malformed sessions with
    an explicit reason while processing valid unrelated sessions. Deduplicate at-least-once records
    by exact session/source identity and reject conflicting duplicate content. Retain coverage,
    dropped counts, requested versus observed outcomes, and useful resolved findings.
-3. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
+4. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
    Treat a finding already linked to an open tracker as context, not a duplicate.
-4. Verify each candidate against the current base. Search existing issues and open changes before
+5. Verify each candidate against the current base. Search existing issues and open changes before
    drafting. Skip work that is complete, explicitly rejected, or already covered. A first-party version
    bump is not proof of resolution: verify the adopted change against the original finding before
    deferring. Capture a new observation in the journal before filing it.
-5. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
+6. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
    validation. Route every authorized creation through
    [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
    denied-external tracking behavior.
-6. Archive only records fully processed across every represented repository, under the repository's
-   retention rules. A one-repository pass leaves a multi-repository session active until the other
+7. Archive only verified records fully processed across every represented repository, and never
+   while any worktree's `outbox_status` reports pending records, under the repository's retention
+   rules. Make one `session_archive` call per session, whose `sessionId` is the archived session,
+   not the caller. Immediately before each call, read that session with `journal_entries` and
+   archive only if its entries match the verified snapshot's by source identity; otherwise leave it
+   for the next pass, because an entry added after the export would never be distilled.
+   Archiving makes the session's metadata immutable, so it needs the archival authorization that
+   local policy requires. A one-repository pass leaves a multi-repository session active until the other
    repositories are reviewed. Report reviewed, fixed, duplicate, deferred, quarantined, and
    actionable dispositions with reasons. Keep the top five themes in human prose without dropping
    underlying findings or unresolved records.
@@ -40,8 +62,10 @@ Use source records only for local verification and leave them in the repository'
 or retention system. Public issue bodies contain only the minimum bounded facts or redacted
 summaries needed to establish the problem, proposed work, relevant areas, and validation. Never
 embed unredacted logs, command output, environment details, provider payloads, or transcript
-content.
+content. A snapshot file is a private local copy of source records: never commit or attach it, or
+copy its contents into an issue.
 
-This skill supplies no journal API, issue repository, labels, milestones, projects, archival
-command, or approval model. Consumer wrappers cannot weaken this export boundary; they provide only
-those local details.
+This skill supplies no issue repository, labels, milestones, projects, or approval model; it reads
+sessions only from the snapshot file that `snapshot_export` writes, and archives them only with
+`session_archive`. Consumer wrappers cannot weaken this export
+boundary; they provide only those local details.