vouchington-tooling 0.41.0 → 0.42.0

package/dist/mcp-server/tools-retrospective.mjs

@@ -0,0 +1,48 @@
+import { ADDITIVE, COVERAGE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, OUTCOMES, READ_ONLY, tool, } from "./tools-schema.mjs";
+export const RETROSPECTIVE_TOOLS = [
+    tool('retrospective_check', 'Reports whether the session already holds a retrospective: { sessionId, saved, entries } ' +
+        'where each entry is { sourceEventId, timestamp, issues, prs } for an entry of type ' +
+        'retrospective, oldest first. sourceEventId narrows the result. A session that was never ' +
+        'created reports saved: false.', READ_ONLY, { sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Only this event id.' } }),
+    tool('retrospective_save', 'Saves the session retrospective after the checkout policy accepts it, and returns the same ' +
+        'verified receipt as journal_append (status, receipt, timestamp, pendingCount, ' +
+        'worktreePendingCount) plus policy.warnings. Pass exactly one of markdown (a finished ' +
+        'document opening with the front matter composeRetrospective writes: date, issues, prs ' +
+        'and optionally session_id, description, work_outcome, feedback_coverage, repositories, ' +
+        'each line key: <JSON>; any that repeat an argument must equal it) or compose (the retrospective ' +
+        'composer input: narrative, date, issues, prs, description, facts, transcript, tools, ' +
+        'architecture, optional knownSensitiveValues; the server adds the rest). compose.transcript ' +
+        'takes only { sessionId?, harnessSessionId? } (sessionId must be the call sessionId; the ' +
+        'transcript is found by harnessSessionId, the harness session UUID, else by sessionId when ' +
+        'that is a UUID, in the default session roots of the worktree) or { status, reason } to report it ' +
+        'unassessed; any path override is rejected. The server redacts its blackboard token ' +
+        'from the document before the policy sees it. dryRun returns ' +
+        '{ markdown, policy: { warnings } } and writes nothing. The worktree package.json may ' +
+        'declare "vouchington-tooling": { "policy": "<module>" }; its validateRetrospective export ' +
+        'runs in a child process, and any error it reports rejects the save with nothing written. ' +
+        'Policy tools need a server launched inside a repository worktree. The server owns the ' +
+        'timestamp. sourceEventId defaults to retrospective-<sessionId> (retrospective-<sha256 hex of the ' +
+        'sessionId> when that exceeds 256 bytes); saving changed content ' +
+        'under the same sourceEventId is an event-conflict, so a revision needs a new ' +
+        'sourceEventId. Repeat an identical markdown call to retry. compose regenerates the document, ' +
+        'so deliver a retained compose save with outbox_flush instead of repeating it. Counts ' +
+        'follow journal_append.', ADDITIVE, {
+        ...IDENTITY,
+        mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
+        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        feedbackCoverage: COVERAGE,
+        repositories: {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1,
+            description: 'Exact owner/name repositories; stored sorted, deduplicated and lowercase. Default: ' +
+                'the front matter repositories, else the policy pullRequestDefaults repositories; ' +
+                'an error when none.',
+        },
+        markdown: { type: 'string', description: 'Finished retrospective markdown.' },
+        compose: { type: 'object', description: 'Composer input; exclusive with markdown.' },
+        sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Stable event id.' },
+        category: { type: 'string', description: 'Optional context; never changes entry type.' },
+        dryRun: { type: 'boolean', description: 'Compose and validate only; write nothing.' },
+    }, [...IDENTITY_REQUIRED, 'mode', 'workOutcome', 'feedbackCoverage']),
+];

package/dist/mcp-server/tools-schema.d.mts

@@ -0,0 +1,54 @@
+export type JsonSchema = Record<string, unknown>;
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, JsonSchema>;
+        required: string[];
+        additionalProperties: false;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare const ID_PATTERN = "^[A-Za-z0-9._:-]+$";
+export declare const PARENT_SESSION_ID: JsonSchema;
+export declare const AGENT: JsonSchema;
+export declare const VERSION: JsonSchema;
+export declare const OUTCOMES: string[];
+export declare const COVERAGE: JsonSchema;
+export declare const READ_ONLY: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const IDEMPOTENT_ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const MUTATING: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare function tool(name: string, description: string, annotations: ToolDefinition['annotations'], properties?: Record<string, JsonSchema>, required?: string[]): ToolDefinition;
+export declare const IDENTITY: {
+    parentSessionId: JsonSchema;
+    agent: JsonSchema;
+    version: JsonSchema;
+};
+export declare const IDENTITY_REQUIRED: string[];

package/dist/mcp-server/tools-schema.mjs

@@ -0,0 +1,70 @@
+export 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.',
+};
+export const PARENT_SESSION_ID = {
+    type: ['string', 'null'],
+    pattern: ID_PATTERN,
+    maxLength: 256,
+    description: 'Direct parent session id, or null for a root session.',
+};
+export const AGENT = { type: 'string', maxLength: 128, description: 'Agent name.' };
+export const VERSION = { type: 'string', maxLength: 128, description: 'Agent version.' };
+export const OUTCOMES = [
+    'in-progress',
+    'success',
+    'failure',
+    'cancelled',
+    'timed-out',
+    'no-change',
+    'policy-refusal',
+    'unknown',
+];
+const COVERAGE_STATUSES = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
+export const COVERAGE = {
+    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.',
+};
+export const READ_ONLY = flags(true, false, true);
+export const ADDITIVE = flags(false, false, false);
+export const IDEMPOTENT_ADDITIVE = flags(false, false, true);
+export const MUTATING = flags(false, true, true);
+function flags(readOnly, destructive, idempotent) {
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: destructive,
+        idempotentHint: idempotent,
+        openWorldHint: false,
+    };
+}
+export 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,
+    };
+}
+export const IDENTITY = { parentSessionId: PARENT_SESSION_ID, agent: AGENT, version: VERSION };
+export const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];

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

@@ -1,19 +1,2 @@
-type JsonSchema = Record<string, unknown>;
-export type ToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, JsonSchema>;
-        required: string[];
-        additionalProperties: false;
-    };
-    annotations: {
-        readOnlyHint: boolean;
-        destructiveHint: boolean;
-        idempotentHint: boolean;
-        openWorldHint: boolean;
-    };
-};
+import { type ToolDefinition } from './tools-schema.mts';
 export declare const TOOLS: readonly ToolDefinition[];
-export {};

package/dist/mcp-server/tools.mjs

@@ -1,62 +1,5 @@
-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 { 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 +21,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 +45,7 @@ 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,
     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. Pull request tools are a later phase.
 
 ## 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,92 @@ 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`   | `{}`                                                                                                                                                                        | `{ repositories: string[] }`                | 120 s   |
+| `validatePullRequest`   | reserved for the pull request tools                                                                                                                                         | `{ 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.
+
 ## 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.42.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

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.