vouchington-tooling 0.24.0 → 0.25.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,127 @@
+# 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                                                                                                                                                                                            | the session's entries as markdown                                                               |
+| `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.
+
+`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.0",
+  "version": "0.25.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/stacked-prs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacked-prs
-description: Drain native GitHub stacks from the bottom ready layer.
+description: Drain native GitHub stacks from the bottom ready layer; a ready lower layer does not freeze later work.
 ---
 
 # Stacked pull requests
@@ -36,6 +36,20 @@ a stack, and who may authorize a merge.
 - A stall blocks only layers that depend on it. Ready the others. Pause the whole drain only when
   nothing further can be readied without the blocked layer.
 - Act only on layers assigned to you. Report the other layers; do not change them.
+- One worker per native stack implements that stack and runs its shepherd poll. The parent does
+  not poll. It reconciles stacks, starts a worker, and carries merge questions to the human.
+- Start shepherding when the first owned pull request exists.
+- A lower layer is in decent shape when it is committed, its local checks have passed, its pull
+  request is open with an updated body, and shepherding has started. Decent shape does not mean
+  green CI, ready for review, or merged.
+- Start the next dependent layer once the lower layer is in decent shape. Do not wait for merge,
+  a ready-delay, or green CI.
+- A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
+  layer. Keep readying every other owned layer.
+- Independent stacks run at the same time, one worker each. Dependent unmerged work is another
+  layer of the same stack, not a second stack whose base is an unmerged head.
+- At most one poll process per stack. The parent does not run a second poll for the same stack.
+- This skill does not grant a merge. Merge authorization stays with the consumer.
 
 Consumer wrapper owns: default branch, stacking tool and commands, merge-selector syntax, and
 merge authorization.