vouchington-tooling 0.41.0 → 0.43.0

package/dist/mcp-server/tools.mjs

@@ -1,62 +1,6 @@
-const ID_PATTERN = '^[A-Za-z0-9._:-]+$';
-const SESSION_ID = {
-    type: 'string',
-    pattern: ID_PATTERN,
-    maxLength: 256,
-    description: 'Explicit session id (URL-safe). Never inferred by the server.',
-};
-const WORKTREE = {
-    type: 'string',
-    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
-        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
-        'launched outside a git worktree.',
-};
-const PARENT_SESSION_ID = {
-    type: ['string', 'null'],
-    pattern: ID_PATTERN,
-    maxLength: 256,
-    description: 'Direct parent session id, or null for a root session.',
-};
-const AGENT = { type: 'string', maxLength: 128, description: 'Agent name.' };
-const VERSION = { type: 'string', maxLength: 128, description: 'Agent version.' };
-const OUTCOMES = [
-    'in-progress',
-    'success',
-    'failure',
-    'cancelled',
-    'timed-out',
-    'no-change',
-    'policy-refusal',
-    'unknown',
-];
-const COVERAGE_STATUSES = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
-const READ_ONLY = flags(true, false, true);
-const ADDITIVE = flags(false, false, false);
-const IDEMPOTENT_ADDITIVE = flags(false, false, true);
-const MUTATING = flags(false, true, true);
-function flags(readOnly, destructive, idempotent) {
-    return {
-        readOnlyHint: readOnly,
-        destructiveHint: destructive,
-        idempotentHint: idempotent,
-        openWorldHint: false,
-    };
-}
-function tool(name, description, annotations, properties = {}, required = []) {
-    return {
-        name,
-        description,
-        inputSchema: {
-            type: 'object',
-            properties: { sessionId: SESSION_ID, worktree: WORKTREE, ...properties },
-            required: ['sessionId', ...required],
-            additionalProperties: false,
-        },
-        annotations,
-    };
-}
-const IDENTITY = { parentSessionId: PARENT_SESSION_ID, agent: AGENT, version: VERSION };
-const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];
+import { ADDITIVE, AGENT, COVERAGE, IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, MUTATING, OUTCOMES, PARENT_SESSION_ID, READ_ONLY, VERSION, tool, } from "./tools-schema.mjs";
+import { PR_TOOLS } from "./tools-pr.mjs";
+import { RETROSPECTIVE_TOOLS } from "./tools-retrospective.mjs";
 export const TOOLS = [
     tool('journal_append', 'Appends one journal entry to the caller session and returns the verified read-back receipt. ' +
         'Nothing is written unless every required field validates. Interactive mode retains the ' +
@@ -78,17 +22,7 @@ export const TOOLS = [
             minItems: 1,
             description: 'Exact owner/name repositories this entry concerns.',
         },
-        feedbackCoverage: {
-            type: 'object',
-            properties: {
-                status: { enum: COVERAGE_STATUSES },
-                sources: { type: 'array', items: { type: 'string' } },
-                droppedCount: { type: 'integer', minimum: 0 },
-            },
-            required: ['status'],
-            additionalProperties: false,
-            description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
-        },
+        feedbackCoverage: COVERAGE,
         category: { type: 'string', description: 'Optional context; never changes entry type.' },
     }, [
         ...IDENTITY_REQUIRED,
@@ -112,6 +46,8 @@ export const TOOLS = [
         'as sourceEventId and diagnostic.', IDEMPOTENT_ADDITIVE),
     tool('session_ensure', 'Idempotently creates a session, or verifies that an existing one has the same identity. ' +
         'Returns the session id and whether it was created.', IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
+    ...RETROSPECTIVE_TOOLS,
+    ...PR_TOOLS,
     tool('snapshot_export', 'Exports non-archived sessions into a private local JSONL file chosen by the blackboard ' +
         'client. Returns the path, counts, checksum, manifest, and cleanupToken; never the records. ' +
         'sessionId identifies the caller.', ADDITIVE, {

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

@@ -11,12 +11,19 @@ export declare const runIsolatedGit: RunTextCommand;
  * or an unsafe repository, is thrown with the cause rather than reported as "outside a worktree".
  */
 export declare function launchWorktreeRoot(cwd: string, runGit: RunTextCommand): Promise<string | undefined>;
+/**
+ * The worktree paths in `git worktree list --porcelain -z` output: NUL-terminated fields, an empty
+ * field ending each record, so a path containing a newline cannot forge a record.
+ */
+export declare function parseWorktreeList(output: string): string[];
 /**
  * Resolves the worktree a tool call may act on. It must be an absolute path that, after
- * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
- * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
- * Git is asked on every call, so worktrees created after the server started are accepted and
- * removed ones are not. Without `requested`, the launch worktree is used when there is one.
+ * resolving symlinks, is exactly the top level of a git worktree. A subdirectory, a relative or
+ * nonexistent path, and a non-git directory are rejected. When the server was launched inside a
+ * repository, the path must also be one of that repository's worktrees (primary or linked), so an
+ * unrelated `git init` directory is refused. A server launched outside any repository accepts the
+ * top level of any worktree. Git is asked on every call, so worktrees created after the server
+ * started are accepted and removed ones are not. Without `requested`, the launch worktree is used.
  */
 export declare function resolveWorktree(input: {
     launchRoot: string | undefined;

package/dist/mcp-server/worktree.mjs

@@ -52,12 +52,33 @@ export async function launchWorktreeRoot(cwd, runGit) {
     }
     return realpath(output.trim());
 }
+/**
+ * The worktree paths in `git worktree list --porcelain -z` output: NUL-terminated fields, an empty
+ * field ending each record, so a path containing a newline cannot forge a record.
+ */
+export function parseWorktreeList(output) {
+    return output
+        .split('\0')
+        .filter((field) => field.startsWith('worktree '))
+        .map((field) => field.slice('worktree '.length));
+}
+/**
+ * The real paths of every worktree of the repository containing `root` (the primary worktree and
+ * each linked one).
+ */
+async function repositoryWorktrees(root, runGit) {
+    const output = await runGit(['-C', root, 'worktree', 'list', '--porcelain', '-z']);
+    const paths = parseWorktreeList(output).map(canonical);
+    return new Set((await Promise.all(paths)).filter((path) => path !== undefined));
+}
 /**
  * Resolves the worktree a tool call may act on. It must be an absolute path that, after
- * resolving symlinks, is exactly the top level of a git worktree (of any repository on the
- * machine). A subdirectory, a relative or nonexistent path, and a non-git directory are rejected.
- * Git is asked on every call, so worktrees created after the server started are accepted and
- * removed ones are not. Without `requested`, the launch worktree is used when there is one.
+ * resolving symlinks, is exactly the top level of a git worktree. A subdirectory, a relative or
+ * nonexistent path, and a non-git directory are rejected. When the server was launched inside a
+ * repository, the path must also be one of that repository's worktrees (primary or linked), so an
+ * unrelated `git init` directory is refused. A server launched outside any repository accepts the
+ * top level of any worktree. Git is asked on every call, so worktrees created after the server
+ * started are accepted and removed ones are not. Without `requested`, the launch worktree is used.
  */
 export async function resolveWorktree(input) {
     const { launchRoot, requested, runGit } = input;
@@ -68,8 +89,12 @@ export async function resolveWorktree(input) {
     if (!isAbsolute(path))
         throw new Error('worktree must be an absolute path to a git worktree');
     const target = await canonical(path);
-    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target)
-        return target;
+    if (target !== undefined && (await launchWorktreeRoot(target, runGit)) === target) {
+        if (launchRoot === undefined || (await repositoryWorktrees(launchRoot, runGit)).has(target))
+            return target;
+        throw new Error(`worktree ${path} is not a worktree of the repository this server was launched in ` +
+            `(${launchRoot}); \`git worktree list\` there names the worktrees it may act on`);
+    }
     throw new Error(`worktree ${path} is not the top level of a git worktree: it must exist and be the ` +
         'directory `git rev-parse --show-toplevel` reports, not a subdirectory of it');
 }

package/docs/mcp-server.md

@@ -6,8 +6,8 @@ a tool argument; there is no temp file, `--file`, or replay command. The server
 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.
+covers the journal, outbox, session, and snapshot tools below. Phase 2 adds the retrospective tools
+and the policy contract they run. Phase 3 adds the pull request tools.
 
 ## Install
 
@@ -82,15 +82,17 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 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 `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
-| `journal_entries` | none                                                                                                                                                                               | `sessionId` and `entries`, every entry oldest first                                                                                              |
-| `outbox_status`   | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
-| `outbox_flush`    | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
-| `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`                                                                                                                    |
+| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                             | Returns                                                                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`       | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
+| `journal_entries`     | none                                                                                                                                                                                     | `sessionId` and `entries`, every entry oldest first                                                                                              |
+| `outbox_status`       | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
+| `outbox_flush`        | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
+| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                    | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
+| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                 | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
+| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown` and `policy.warnings`                                                      |
+| `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
@@ -163,20 +165,166 @@ is unavailable.
 The server sends the same list in its MCP `instructions`, so a harness that surfaces server
 instructions shows it to the agent.
 
+## Retrospective tools and the policy contract
+
+`retrospective_check` reads the session through the same client as `journal_entries` and reports the
+entries whose envelope `type` is `retrospective`. A session that was never created (the blackboard
+answers 404) reports `saved: false`.
+
+`retrospective_save` builds a `retrospective` envelope and writes it exactly as `journal_append`
+does (same receipt, `pendingCount`, `worktreePendingCount`, outbox rules, and server-owned
+timestamp; a `timestamp` argument is rejected). The document comes from `markdown` or from
+`compose`, the input of `composeRetrospective` (`narrative`, `date`, `issues`, `prs`,
+`description`, `facts`, `transcript`, `tools`, `architecture`, optional `knownSensitiveValues`;
+unknown keys are rejected, and the journal audit reads through the server's own client).
+`compose.transcript` accepts only `{ sessionId?, harnessSessionId? }` (`sessionId` must equal the
+call's `sessionId`) or `{ status, reason }` for an unassessed transcript. The transcript is found by
+`harnessSessionId`, the harness's own session UUID, else by the call's `sessionId` when that is a
+UUID; otherwise the call fails rather than reporting the transcript unavailable. When the server's environment names its harness session (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, and so on), only that session's transcript is read (after `/clear` or a thread switch, reconnect the server, or pass `{ status, reason }`); `jsonlPath`, `projectsDir`, `codexSessionsDir`,
+`grokSessionsDir`, and `cwd` are rejected, and the server reads the transcript from the worktree
+and its default session roots. The server's blackboard token, and any `knownSensitiveValues`, are
+redacted from the document before the policy sees it or the envelope is stored. Facts commands
+are killed after 120 seconds. `compose.facts` takes `pr`, `branch`, `noPr`, or `{ status, reason }`;
+`repo` is rejected, so the server's GitHub token never queries a repository other than the
+worktree's. Facts run `git` and `gh` in the worktree as the server's user, honoring its
+repository configuration (which can select helpers that run code), so the worktree, including
+`.git/config`, must be as trusted as the policy module. `dryRun`
+runs every check and returns the document without writing.
+
+The document must open with the front matter `composeRetrospective` writes: lines of
+`key: <JSON value>` between two `---` lines. Recognized keys are `date`, `issues`, `prs` (required),
+`session_id`, `description`, `work_outcome`, `feedback_coverage` (`status`, `sources`,
+`droppedCount`), and `repositories`; anything else, a duplicate, or a malformed line is rejected.
+`session_id`, `work_outcome`, `feedback_coverage`, and `repositories` must equal the arguments when
+present. `repositories` resolves from the argument, else the front matter, else the policy's
+`pullRequestDefaults()` result, else an error, and is stored sorted, deduplicated, and lowercase.
+The default `sourceEventId` is `retrospective-<sessionId>`, or `retrospective-<sha256 hex of the
+sessionId>` when that would exceed 256 bytes. Re-saving identical content returns the
+stored receipt and timestamp. Changed content under the same `sourceEventId` is an
+`event-conflict`; a revision needs a new `sourceEventId`. `compose` regenerates the document from
+the live journal and repository, so repeating a `compose` call is not a retry: when an interactive
+save is retained in the outbox, deliver it with `outbox_flush`.
+
+### Policy module
+
+The consumer's root `package.json` may declare
+`"vouchington-tooling": { "policy": "dev/agent-policy.mts" }`. The path must be relative and, after
+resolving symlinks, stay inside the worktree. Without a declaration the policy checks are skipped.
+Policy tools also require a server launched inside a repository worktree on macOS or Linux (they
+refuse to run on Windows, where the server cannot reap a policy's descendants by process group),
+and refuse to run when `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` is set to a value
+shorter than four characters, which could not be redacted from policy output. Each call runs one named
+export in a fresh child process (`bin/policy-runner.mjs`, started with the server's own Node), never
+inside the server, with the worktree as its working directory and an environment of only `HOME`,
+`PATH` (`/usr/bin`, `/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, the Node directory, and the
+directory of the first `gh` on the server's `PATH`, deduplicated), and `GH_TOKEN` / `GITHUB_TOKEN` when the server has
+them. Blackboard credentials and `NODE_OPTIONS` are not passed. The child still runs as the
+server's user, so this is not a sandbox: on Linux it could read the server's environment from
+`/proc/<server pid>/environ`. Treat the policy module as trusted code. After the runner exits, its
+whole process group is killed, so nothing it started outlives the call. The runner reads
+`{ policyVersion: 1, export, input }` on stdin and writes `{ ok: true, result }` (or
+`{ ok: false, error }`) on stdout; a missing export is skipped.
+
+| Export                  | Input                                                                                                                                                                       | Result                                                         | Timeout |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
+| `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }`                    | 30 s    |
+| `pullRequestDefaults`   | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create`                                                                                           | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, `mode`, and `pr` for an update                                                                                                             | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
+
+Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
+`policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
+shape is an error, never a pass.
+
+## Pull request tools
+
+`vouchington mcp` serves `pr_validate`, `pr_create` and `pr_update` besides the journal and
+retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
+launched inside a repository worktree (they run the checkout policy), and share this structured
+input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), `details` (string array),
+`base` (default `main`), `agent`, optional `model`, `mode` (`interactive` | `autonomous`) and
+`workspaceSetup`. `pr_update` also requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Rendering
+
+```
+## Summary
+
+<summary>
+
+## Impact
+
+<impact>
+
+## Related issues
+
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+
+## Details
+
+<details joined by blank lines>
+
+Workspace setup: <workspaceSetup>
+Agent: <agent>[ (<model>)] session <sessionId>
+Device: <os user>@<lowercased hostname>
+Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
+```
+
+The head branch is the worktree's current branch; a detached HEAD, or a head equal to `base`, is
+rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
+so a consumer policy may reject any `base` other than the default branch; create stacked layers
+with the repository's stack tooling instead.
+
+### Tools
+
+- `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
+base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
+  body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
+- `pr_create` (additive): renders and validates (errors block), then calls the policy
+  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
+  (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
+  `--project`. Returns `{ number, url, warnings }`.
+- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,baseRefName,state`,
+  rejects a pull request that is not `OPEN` or whose head is not the worktree branch, and validates
+  against the live base (an explicit `base` must equal it). It renders, appends the live Shepherd
+  Journal (a `<details><summary>Shepherd Journal</summary>` block, or a legacy `## Shepherd Journal`
+  section to the next H2 or the end; examples in fenced code blocks are ignored), validates with
+  `pr` set (errors block), then runs `gh pr edit <pr> --title --body-file`. More than one journal
+  in the live body, one in the rendered fields, an unclosed journal, or rendered fields that leave
+  a code fence open are rejected rather than guessed. Just before the edit the live body is read
+  again, and the update aborts if its journal changed meanwhile. Nothing else is carried over from
+  the live body. Returns `{ number, url, warnings }`.
+
+Every field is redacted of `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, and `GITHUB_TOKEN` before
+rendering, the policy, or `gh`; a worktree branch name containing one is rejected. `title` and
+`workspaceSetup` must be single lines, and the title is limited to 256 characters after redaction.
+
+### gh access
+
+`gh` is found in the absolute directories of the server's `PATH` (relative entries are skipped,
+since they would resolve inside the target worktree), else at `/opt/homebrew/bin/gh`, `/usr/local/bin/gh` or
+`/usr/bin/gh`; otherwise the tool fails with "gh CLI not found on PATH; install gh or add it to the
+server's PATH". It runs with the worktree as its working directory and the server environment
+without `AGENT_BLACKBOARD_URL`, `AGENT_BLACKBOARD_TOKEN`, and `GH_REPO` (which would point it at
+another repository), and each call is killed after 120 seconds.
+
 ## Worktree validation
 
 `worktree` is checked on every call. It must be an absolute path that, after resolving symlinks,
 equals the top level of a git worktree, that is, what `git rev-parse --show-toplevel` prints when
-run in it. Any git worktree on the machine is accepted, including one of a repository unrelated to
-the launch directory, so the tools can act on every checkout the user can reach. Worktrees created
-after launch are accepted and removed ones are refused. Rejected: a subdirectory of a worktree, a
+run in it. When the server was launched inside a repository, the real path must also equal one of
+the `worktree` entries of `git worktree list --porcelain` run in the launch root (the primary
+worktree or a linked one), so an unrelated repository is refused. A server launched outside any
+repository accepts the top level of any git worktree for the journal tools, but refuses the policy
+tools. Worktrees created after launch are accepted and removed ones are refused. Rejected: a subdirectory of a worktree, a
 relative or nonexistent path, and a directory that is not in a git worktree. Git runs without
 `GIT_*` variables, so `GIT_DIR` cannot redirect the check, and with `LC_ALL=C` and no `LANGUAGE`, so
 its "not a git repository" diagnostic is never translated.
 
 `worktree` only chooses where the outbox lives. It is not a trust boundary for loading code: the
-server never imports modules from it, and a tool that needs to must first get a repository allowlist
-from the machine registration.
+server never imports modules from it. The policy tools run the declared module only in a child
+process without blackboard credentials, as described above.
 
 When `worktree` is omitted, the launch directory's worktree top level is used if the launch
 directory is inside one, and it is validated like any explicit path. If the server was launched

package/package.json

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

package/skills/pr-description/SKILL.md

@@ -54,6 +54,14 @@ not evidence of a miss; classify genuine CI-only or external infrastructure fail
 Retain confirmed gap records after CI turns green. Diagnose the failure through the repository's
 CI investigation workflow; a failed status alone does not establish a gap.
 
+Create, update, and validate pull requests through the `pr_create`, `pr_update`, and `pr_validate`
+MCP tools with structured input, not by hand-writing a body: pass `title`, `summary`, `impact`,
+`relatedIssues` (`closes` or `refs`, each with a reason), `details` (Markdown paragraphs or
+bullets), `base`, `agent`, optional `model`, `mode`, and `workspaceSetup`. The server renders the
+required headings and provenance lines, runs the repository's policy validation, and blocks on its
+errors, so put the guidance above into `summary`, `impact`, and `details`. Run `pr_validate` first
+to preview the rendered body. `pr_update` preserves the live Shepherd Journal.
+
 Use the repository's approved PR tooling and preserve sections managed by its review automation
 verbatim. Close only issues fully resolved and explain non-closing issue links. Apply this guidance
 to descriptions being created or updated, not a bulk rewrite of historical pull requests.

package/skills/retrospective/SKILL.md

@@ -14,7 +14,8 @@ local `AGENTS.md`, and journal guidance first.
 
 1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
    material new observation before filing a follow-up issue. Preserve entry-level repository tags.
-2. Generate routine repository and transcript facts with the approved composer. Keep exact factual
+2. Generate routine repository and transcript facts with the approved composer: pass `compose` to
+   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Keep exact factual
    section markers generated, preserve unavailable counts, and never replace missing evidence with
    invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
 3. Record work outcome, feedback coverage, and delivery independently. Success, failure,
@@ -30,7 +31,9 @@ local `AGENTS.md`, and journal guidance first.
 5. Keep the top five findings or improvements in the human prose. The bounded durable evidence can
    retain additional relevant findings; a prose limit is not permission to silently discard them.
    Separate recurring root causes from one-off noise and preserve existing issue references.
-6. Save through the shared validated writer. Interactive outages use the approved bounded private
+6. Check for an existing retrospective with the `retrospective_check` MCP tool and save with
+   `retrospective_save`, never a CLI. A revision of changed content needs a new `sourceEventId`.
+   Interactive outages use the approved bounded private
    outbox with visible pending count; failed persistence blocks capture. Autonomous reporting stays
    online and never uses that outbox to authorize an attempt or completion. Report the acknowledged
    record/receipt, or the actual pending/blocked state and next replay action.