vouchington-tooling 0.24.1 → 0.26.0

package/dist/session-friction/report.mjs

@@ -1,61 +1,8 @@
 import { eventLimit, readFrictionLog, requireDirectory } from './log.mjs';
-import { buildCiFailuresSection, getConformingGroups } from './ci-failures.mjs';
+import { buildCiFailuresSection, getConformingGroups, incompleteCiSection } from './ci-failures.mjs';
+import { errorMessage, scanJournal } from './journal.mjs';
 import { buildSandboxSection } from './sandbox.mjs';
 import { validateSessionId } from './session-id.mjs';
-const JOURNAL_ENTRY_MAX_COUNT = 500;
-const JOURNAL_MARKDOWN_MAX_BYTES = 10_000;
-const JOURNAL_TOTAL_MAX_BYTES = 1_000_000;
-function journalData(entry) {
-    try {
-        const data = entry?.data;
-        return data ? { type: data.type, markdown: data.markdown } : undefined;
-    }
-    catch {
-        return 'unreadable';
-    }
-}
-async function collectEntries(entries) {
-    const result = [];
-    let consumed = 0;
-    let inspectedBytes = 0;
-    let retainedBytes = 0;
-    let truncated = false;
-    for await (const entry of entries) {
-        consumed++;
-        const scanned = journalData(entry);
-        if (scanned === 'unreadable')
-            truncated = true;
-        const data = scanned === 'unreadable' ? undefined : scanned;
-        const markdown = data?.markdown;
-        if (data?.type === 'journal' && typeof markdown !== 'string')
-            truncated = true;
-        if (data?.type === 'journal' && typeof markdown === 'string') {
-            const bytes = Buffer.byteLength(markdown);
-            inspectedBytes += bytes;
-            if (bytes > JOURNAL_MARKDOWN_MAX_BYTES)
-                truncated = true;
-            if (bytes <= JOURNAL_MARKDOWN_MAX_BYTES && retainedBytes + bytes <= JOURNAL_TOTAL_MAX_BYTES) {
-                result.push({ data: { type: 'journal', markdown } });
-                retainedBytes += bytes;
-            }
-        }
-        if (consumed >= JOURNAL_ENTRY_MAX_COUNT ||
-            inspectedBytes >= JOURNAL_TOTAL_MAX_BYTES ||
-            retainedBytes >= JOURNAL_TOTAL_MAX_BYTES) {
-            truncated = true;
-            break;
-        }
-    }
-    return { entries: result, truncated };
-}
-function errorMessage(error) {
-    try {
-        return error instanceof Error ? error.message : String(error);
-    }
-    catch {
-        return '[unprintable error]';
-    }
-}
 function sandboxMarkdown(friction) {
     if (friction.status === 'events')
         return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events)}`;
@@ -64,9 +11,6 @@ function sandboxMarkdown(friction) {
     const status = friction.status === 'empty' ? 'none observed' : 'unavailable (no friction log)';
     return `## Sandbox & Permission Audit\nStatus: ${status}`;
 }
-function incompleteCiSection(markdownBlocks) {
-    return ['## CI Failures\nStatus: unavailable (journal scan incomplete)', ...markdownBlocks].join('\n\n');
-}
 function reportFromLog(sessionId, logOptions, journal) {
     try {
         const friction = readFrictionLog(sessionId, logOptions);
@@ -113,24 +57,16 @@ export async function buildSessionFrictionReport(sessionId, options) {
     validateSessionId(sessionId);
     requireDirectory(options.directory);
     eventLimit(options.maxEvents);
-    let journal;
-    try {
-        const loaded = await options.journalLoader(sessionId);
-        if (loaded.status === 'not-found')
-            journal = { status: 'ok', markdownBlocks: [], truncated: false };
-        else {
-            const collected = await collectEntries(loaded.entries);
-            journal = {
+    const scanned = await scanJournal(sessionId, options.journalLoader);
+    const journal = scanned.status === 'unreachable'
+        ? scanned
+        : scanned.status === 'not-found'
+            ? { status: 'ok', markdownBlocks: [], truncated: false }
+            : {
                 status: 'ok',
-                markdownBlocks: getConformingGroups(collected.entries),
-                truncated: collected.truncated,
+                markdownBlocks: getConformingGroups(scanned.entries),
+                truncated: scanned.truncated,
             };
-        }
-    }
-    catch (error) {
-        const diagnostic = errorMessage(error);
-        journal = { status: 'unreachable', diagnostic };
-    }
     const report = reportFromLog(sessionId, options, journal);
     if (journal.status === 'unreachable') {
         const diagnostic = report.diagnostic

package/docs/mcp-server.md

@@ -0,0 +1,134 @@
+# MCP server
+
+`vouchington mcp` serves the [agent-blackboard](../README.md#validated-feedback-and-delivery)
+journal operations to an agent over stdio (Model Context Protocol). An agent passes the markdown as
+a tool argument; there is no temp file, `--file`, or replay command. The server builds on the
+existing `vouchington-tooling/agent-blackboard` exports and adds no provider protocol.
+
+Phase 1 of [vouchington-tooling#324](https://github.com/vouchington/vouchington-tooling/issues/324)
+covers the journal, outbox, session, and snapshot tools below. Retrospective and pull request tools
+are later phases.
+
+## Install
+
+The server needs three packages next to `vouchington-tooling`. The last two are optional peer
+dependencies, so nothing else in the CLI requires them:
+
+```bash
+pnpm add -D vouchington-tooling agent-blackboard@^0.6.0
+pnpm add -D @modelcontextprotocol/sdk zod
+```
+
+`zod` is required by the SDK. When the SDK is missing, `vouchington mcp` writes a message naming the
+package to stderr and exits with status 1. `agent-blackboard` is resolved from the validated
+worktree at call time (`createRequire` on `<worktree>/package.json`), never from this package.
+
+The connection comes from `AGENT_BLACKBOARD_URL` and `AGENT_BLACKBOARD_TOKEN` in the server's
+environment. The server never searches for, prints, or mints them.
+
+## Launch
+
+```bash
+vouchington mcp
+```
+
+The command takes no arguments. Start it inside the repository's git worktree: that repository
+defines which worktrees the tools accept. stdout carries only protocol frames, and diagnostics go
+to stderr.
+
+## Tools
+
+Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 characters) that the
+server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
+as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
+
+| 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                                                                                                                                                                                            | `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`                                       |
+| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                 | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                           |
+| `session_archive` | none                                                                                                                                                                                            | `sessionId`, `archived: true`                                                                   |
+
+`journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
+anything is written, so a missing required field writes nothing. It returns the verified read-back
+result of `writeFeedback`. Delivery is at least once. The envelope includes its timestamp, so when
+retrying the same `sourceEventId`, resend the same content and the `timestamp` the first call
+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
+`agent-blackboard` client chooses a private file and returns its path. `session_archive` is the one
+destructive tool; archived metadata is immutable, while entries stay appendable.
+
+The outbox lives at `<worktree>/.local/blackboard-outbox` and is used only in interactive mode.
+Autonomous mode forbids a filesystem outbox, so a failed delivery is an error.
+
+## Worktree validation
+
+`worktree` must be an absolute path that, after resolving symlinks, exactly matches an entry of
+`git worktree list --porcelain` for the repository the server was launched from. The list is read on
+every call, so worktrees created after launch are accepted and removed ones are refused. Anything
+else is rejected: a subdirectory of a worktree, a relative or nonexistent path, and a separate
+repository, including one made with `git init` elsewhere. It defaults to the launch worktree's root.
+Git runs without `GIT_*` variables, so `GIT_DIR` cannot redirect the check.
+
+## Registering the server
+
+The commands below run `vouchington` from the repository's own `node_modules`, so a fresh worktree
+uses the version its lockfile pins. Set the blackboard credentials in the environment the harness
+gives the server.
+
+Claude Code, `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vouchington-tooling": {
+      "command": "bash",
+      "args": ["-c", "exec \"$(git rev-parse --show-toplevel)/node_modules/.bin/vouchington\" mcp"]
+    }
+  }
+}
+```
+
+Codex, `.codex/config.toml`:
+
+```toml
+[mcp_servers.vouchington-tooling]
+command = "bash"
+args = ["-c", "exec \"$(git rev-parse --show-toplevel)/node_modules/.bin/vouchington\" mcp"]
+default_tools_approval_mode = "approve"
+required = false
+```
+
+Approving every tool of the server at once:
+
+- Claude Code permission rule: `mcp__vouchington-tooling__*`
+- Cursor permission rule: `Mcp(vouchington-tooling:*)`
+- Codex: `default_tools_approval_mode = "approve"` above
+
+## What is verified
+
+Covered by this package's tests: the tool list and schemas, every tool's success and rejection
+paths against a faked blackboard client, the worktree gate against real temporary git repositories,
+an in-process client and server round trip through the SDK's in-memory transport, and a spawned
+`vouchington mcp` process driven over real stdio.
+
+Not verified, and tracked as the unchecked Phase 0 checklist in
+[#324](https://github.com/vouchington/vouchington-tooling/issues/324): each harness's approval
+syntax and whether the rules above take effect, the working directory after entering a worktree,
+environment interpolation and credential passing, `gh` authentication, behavior in a freshly
+created worktree, and connectivity from automation. Treat the registration snippets and permission
+rules as untested per harness until that checklist is complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.24.1",
+  "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": {
@@ -352,21 +352,26 @@
     "picomatch": "4.0.7",
     "remark": "15.0.1",
     "remark-gfm": "4.0.1",
-    "smol-toml": "1.8.0",
+    "smol-toml": "1.9.0",
     "spdx-expression-parse": "5.0.0",
     "yaml": "2.9.1"
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
+    "@modelcontextprotocol/sdk": "1.31.0",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.0"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "typescript": ">=5",
     "vitest": ">=5"
   },
   "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },

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.