vouchington-tooling 0.26.0 → 0.28.0

package/dist/mcp-server/tools.mjs

@@ -59,7 +59,13 @@ const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];
 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 ' +
-        'envelope in the worktree outbox when the blackboard is unreachable.', ADDITIVE, {
+        'envelope in the worktree outbox when the blackboard is unreachable. The server owns the ' +
+        'entry timestamp and returns it. An event is identified by sessionId, sourceEventId, and ' +
+        'content, never by timestamp: to retry, repeat the identical call, and a retry of an ' +
+        'event already stored or retained reports the stored timestamp instead of a new one. The ' +
+        'same sourceEventId with different content is an event-conflict. pendingCount counts ' +
+        'unsent records of the caller sessionId; worktreePendingCount counts those of every ' +
+        'session in the worktree outbox (both 0 in autonomous mode, which never uses an outbox).', ADDITIVE, {
         ...IDENTITY,
         mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
         markdown: { type: 'string', description: 'Journal note as markdown text (max 12000 bytes).' },
@@ -82,11 +88,6 @@ export const TOOLS = [
             additionalProperties: false,
             description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
         },
-        timestamp: {
-            type: 'string',
-            description: 'Optional ISO 8601 time; defaults to now and is returned. Reuse the same sourceEventId ' +
-                'and timestamp when retrying, because the whole envelope must match.',
-        },
         category: { type: 'string', description: 'Optional context; never changes entry type.' },
     }, [
         ...IDENTITY_REQUIRED,
@@ -100,10 +101,11 @@ export const TOOLS = [
     tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
         'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
         'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
-    tool('outbox_status', 'Reports how many unsent journal records the worktree outbox retains. sessionId identifies ' +
-        'the caller; the count covers the whole outbox.', READ_ONLY),
-    tool('outbox_flush', 'Delivers retained outbox records and returns the remaining count. sessionId identifies the ' +
-        'caller; the flush covers every record in the worktree outbox.', IDEMPOTENT_ADDITIVE),
+    tool('outbox_status', 'Reports unsent journal records in the worktree outbox. pendingCount and status (empty or ' +
+        'pending) cover the caller sessionId only; worktreePendingCount covers every session.', READ_ONLY),
+    tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
+        'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
+        'records of the caller sessionId; worktreePendingCount covers every session.', 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),
     tool('snapshot_export', 'Exports non-archived sessions into a private local JSONL file chosen by the blackboard ' +

package/dist/pnpm-install/pnpm-install-fake-pnpm.test-helpers.mjs

@@ -7,7 +7,7 @@ if [ "\${1:-}" = m ]; then
   exit 0
 fi
 if [ "\${1:-}" = --version ]; then
-  printf '%s\\n' "\${PNPM_VERSION:-11.0.0}"
+  printf '%s\\n' "\${PNPM_VERSION:-1.0.0}"
   exit 0
 fi
 printf '%s\\n' "$*" >> "$PNPM_LOG"
@@ -23,7 +23,7 @@ write_modules() {
 print_release_age_violation() {
   printf '%s\\n' '✗ Lockfile failed supply-chain policy check (1 entries in 0.1s)'
   printf '%s\\n' '[ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION] 1 lockfile entries failed verification:'
-  printf '%s\\n' '  undici@8.10.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
+  printf '%s\\n' '  fixture-package@1.0.0 was published at 2026-08-03T15:06:33.000Z, within the minimumReleaseAge cutoff (2026-08-02T04:48:10.357Z)'
 }
 if [ "\${PNPM_FAIL_CALL:-0}" = "$calls" ]; then
   if [ -n "\${PNPM_FAIL_RELEASE_AGE:-}" ]; then print_release_age_violation; fi

package/docs/mcp-server.md

@@ -42,22 +42,36 @@ 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 `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`                                                                   |
+| 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`                                                                           |
+| `outbox_flush`    | none                                                                                                                                                                               | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `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.
+result of `writeFeedback`. Delivery is at least once. Markdown is limited to 12000 bytes.
+
+The server owns the entry `timestamp`: the tool takes no `timestamp` argument and rejects one, so an
+agent cannot fabricate it, and the result returns the timestamp it reports. An event is identified by
+`sessionId`, `sourceEventId`, and content; the timestamp is not part of that identity. The server
+stamps each attempt with the current time, and the delivery step compares the new attempt with what
+the blackboard or the worktree outbox already holds while ignoring only `timestamp`. To retry, repeat
+the identical call. A retry of an event that is already stored, or already retained in the outbox,
+is the same event: it writes nothing, drops the duplicate retained record, and returns the stored
+record's `timestamp` and `receipt`, so repeated retries report the same timestamp, including after a
+server restart and when the provider was unreachable for the retry. An outbox record that was
+delivered before the retry is recognized the same way when it is flushed, so it drains instead of
+blocking. Any difference in the other envelope fields under the same `sessionId` and
+`sourceEventId` is an `event-conflict` (or a conflict with the retained unsent record) and writes
+nothing. If an autonomous write of the same event lands between the check and the append, both
+entries exist, but the report names the earliest stored one and later retries report it again.
+Admission freshness (`verifyFreshFeedback`) keeps its stricter rule: any earlier record of the event,
+whatever its timestamp, is a conflict.
 
 `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
@@ -67,7 +81,13 @@ order, so they are sorted stably by `createdAt`, oldest first. An empty session
 `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
+The outbox is per worktree, so the results name two counts apart. `pendingCount` is the number of
+unsent records of the caller's `sessionId`, and `status` (`empty` or `pending`) follows it.
+`worktreePendingCount` is the number of unsent records of every session in the worktree outbox. Both
+are 0 in autonomous mode, which has no outbox. `outbox_flush` delivers every retained record in the
+worktree, whichever session wrote it, so its `deliveredCount` covers the whole flush while
+`pendingCount` and `worktreePendingCount` report what remains. A record that cannot be delivered, for
+example after an `event-conflict`, stays in the count of the session that wrote 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.
@@ -75,6 +95,22 @@ 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.
 
+### Tool names by harness
+
+Each harness names the same tools differently, and some load them on demand. The names in this page
+are the bare tool names; find yours by searching for `journal_append` before concluding the server
+is unavailable.
+
+| Harness     | `journal_append` is called                                                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Claude Code | `mcp__vouchington-tooling__journal_append`                                                                               |
+| Codex       | `mcp__vouchington_tooling__journal_append` (the server name's hyphen becomes an underscore)                              |
+| Cursor      | deferred: look it up with `GetDynamicTools` and call it with `CallDynamicTool` under the `vouchington-tooling` namespace |
+| Grok        | `vouchington-tooling__journal_append`, found with `search_tool` and called with `use_tool`                               |
+
+The server sends the same list in its MCP `instructions`, so a harness that surfaces server
+instructions shows it to the agent.
+
 ## Worktree validation
 
 `worktree` must be an absolute path that, after resolving symlinks, exactly matches an entry of
@@ -119,6 +155,11 @@ Approving every tool of the server at once:
 - Cursor permission rule: `Mcp(vouchington-tooling:*)`
 - Codex: `default_tools_approval_mode = "approve"` above
 
+Cursor also asks each user to approve loading a project server, separately from the permission rule
+above, and the rule does not replace it. Approve it once, interactively, with
+`cursor-agent mcp enable vouchington-tooling`. Headless `cursor-agent -p` does not keep that
+approval: pass `--approve-mcps` on every run.
+
 ## What is verified
 
 Covered by this package's tests: the tool list and schemas, every tool's success and rejection
@@ -126,6 +167,9 @@ paths against a faked blackboard client, the worktree gate against real temporar
 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.
 
+The per-harness tool names and the Cursor approval steps come from headless smoke runs of the
+server in each harness, not from this package's tests.
+
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -346,8 +346,8 @@
   "dependencies": {
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
-    "csv-parse": "7.0.2",
-    "csv-stringify": "6.8.3",
+    "csv-parse": "7.0.3",
+    "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
     "picomatch": "4.0.7",
     "remark": "15.0.1",

package/scripts/gha/gha-collaborator-trust.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Classify GitHub authors by their live permission on one repository.
+#
+# usage:  gha-collaborator-trust.sh <owner/repo> [--allow-bot <login>]... < authors.json
+# stdin:  JSON array of {"login": string, "type": string} (GitHub user objects work as-is).
+# stdout: {"trusted": [login...], "untrusted": [login...]}, each sorted and deduplicated.
+#
+# A user is trusted when the legacy `permission` field is admin or write (maintain maps to
+# write). A GitHub App bot (type "Bot") is trusted only when its login is passed with
+# --allow-bot, because an app with only issue or pull-request write access can still comment.
+# A definitive 404 means no permission. Any other lookup failure exits non-zero so callers
+# fail closed.
+set -euo pipefail
+
+usage() {
+  echo "usage: gha-collaborator-trust.sh <owner/repo> [--allow-bot <login>]... < authors.json" >&2
+  exit 2
+}
+
+[ "$#" -ge 1 ] || usage
+repository="$1"
+shift
+[[ "$repository" =~ ^[A-Za-z0-9_-][A-Za-z0-9_.-]*/[A-Za-z0-9_-][A-Za-z0-9_.-]*$ ]] || usage
+
+allowed_bots=$'\n'
+while [ "$#" -gt 0 ]; do
+  if [ "$1" != "--allow-bot" ] || [ "$#" -lt 2 ] || ! [[ "$2" =~ ^[A-Za-z0-9-]+\[bot\]$ ]]; then
+    usage
+  fi
+  allowed_bots+="$2"$'\n'
+  shift 2
+done
+
+input="$(cat)"
+if ! jq -e '
+  type == "array" and all(.[];
+    type == "object"
+    and (.login | type) == "string" and (.login | length) > 0
+    and ((.type | type) == "string" or .type == null))' >/dev/null 2>&1 <<<"$input"; then
+  echo "::error::gha-collaborator-trust: stdin must be a JSON array of {login, type}" >&2
+  exit 2
+fi
+rows="$(jq -r 'unique_by(.login) | .[] | [.login, (.type // "")] | @tsv' <<<"$input")"
+
+results="$(mktemp)"
+errors="$(mktemp)"
+trap 'rm -f "$results" "$errors"' EXIT
+
+while IFS=$'\t' read -r login type; do
+  [ -n "$login" ] || continue
+  verdict=untrusted
+  if [ "$type" = "Bot" ]; then
+    if [[ "$allowed_bots" == *$'\n'"$login"$'\n'* ]]; then
+      verdict=trusted
+    fi
+  elif [[ "$login" =~ ^[A-Za-z0-9-]+$ ]]; then
+    if permission="$(gh api "repos/$repository/collaborators/$login/permission" --jq '.permission' 2>"$errors")"; then
+      case "$permission" in
+        admin | write) verdict=trusted ;;
+      esac
+    elif ! grep -q 'HTTP 404' "$errors"; then
+      cat "$errors" >&2
+      echo "::error::gha-collaborator-trust: permission lookup failed for $login" >&2
+      exit 1
+    fi
+  fi
+  printf '%s\t%s\n' "$verdict" "$login" >>"$results"
+done <<<"$rows"
+
+jq -Rn '
+  [inputs | split("\t")] as $rows
+  | {
+      trusted: [$rows[] | select(.[0] == "trusted") | .[1]] | sort,
+      untrusted: [$rows[] | select(.[0] == "untrusted") | .[1]] | sort
+    }' <"$results"

package/skills/blackboard/SKILL.md

@@ -15,21 +15,29 @@ 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.
+`snapshot_export`, and `session_archive`. Harnesses name them differently, so match the bare tool
+name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
+underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
+or the `vouchington-tooling` namespace reached through `GetDynamicTools` and `CallDynamicTool`.
 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.
+- `snapshot_export`, `outbox_status`, and `outbox_flush`: only the caller. The outbox is per
+  worktree, so `outbox_status` and `outbox_flush` report two counts: `pendingCount` is the unsent
+  records of that `sessionId`, and `worktreePendingCount` is the unsent records of every session in
+  the worktree outbox. `outbox_flush` delivers every retained record in the worktree.
 
 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.
+Search for `journal_append` (by bare name, so every prefix matches) before concluding the server is
+unavailable; a deferred harness lists the tool only on request. If the search finds no such tool
+because the server is not registered, not connected, or not approved, stop and report that the
+journal server is unavailable, and name any per-user approval the harness still needs to load
+it (the consumer wrapper documents it). 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
@@ -40,11 +48,10 @@ report that the journal server is unavailable. Do not fall back to a CLI command
 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
+   canonical exact `repositories`, and explicit `feedbackCoverage`. Never pass a `timestamp`: the
+   server owns it, rejects the argument, and returns the timestamp it used. 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`.
@@ -55,10 +62,11 @@ report that the journal server is unavailable. Do not fall back to a CLI command
    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.
+   `journal_append` reports it as pending. Report `pendingCount` (this session's unsent records),
+   and `worktreePendingCount` when other sessions' records are also unsent, from `journal_append`
+   or `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
@@ -66,9 +74,11 @@ report that the journal server is unavailable. Do not fall back to a CLI command
    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
+   retry a pending or failed append, repeat the identical `journal_append` call with the same
+   `sourceEventId` and content. The server's timestamp is not part of an event's identity, so a
+   retry of an event already stored or retained reports the stored timestamp, even after a restart
+   or an outage. The same `sourceEventId` with different content is rejected as a conflict, so use
+   a new `sourceEventId` for a changed note. 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

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.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.10.0",
+      "pluginVersion": "0.11.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -38,26 +38,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -70,26 +70,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "planning/SKILL.md",
       "prerequisites": ["github-issue"]
     },
@@ -103,65 +103,71 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.2.0",
+      "pluginVersion": "0.3.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.2.0",
+      "pluginVersion": "0.3.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
+    {
+      "name": "postgres-schema-design",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.3.0",
+      "path": "postgres-schema-design/SKILL.md"
+    },
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "review-ci-logs/SKILL.md",
       "prerequisites": ["github-actions-checklist", "pr-description"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.10.0",
+      "pluginVersion": "0.11.0",
       "path": "static-analysis-checklist/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },

package/skills/postgres-node-performance-tuning/references/performance-patterns.md

@@ -12,3 +12,25 @@ Check query predicates, joins, ordering, and selected columns against index shap
 evidence to confirm planner behavior. Add extended statistics only when observed estimates show a
 correlation problem; verify the statistics are collected and used. Partitioning can reduce scanned
 data, but it does not replace suitable local indexes or predicates that permit pruning.
+
+## Query shapes
+
+Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
+`NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
+UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
+Read and return tables with explicit columns: no `SELECT *`, `alias.*`, or `RETURNING *`.
+A view may use `*` when its reviewed column list is the reader contract.
+
+Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CTE, not
+`OFFSET 0`. Constrain a partitioned table's partition key, or document the reason for a
+cross-partition query. Choose the partition key from dominant access patterns; a hot reader
+of `RANGE (id)` needs an id or time bound.
+
+A UUIDv7 child cannot predate its parent. For a `RANGE (id)` child read by parent id, use a
+shared lower-bound helper equivalent to
+`id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` to prune earlier
+partitions; the overlap allows clock skew. Rate limits query an actor-keyed table rather than
+recipient-keyed fan-out rows. Verify actual pruning with EXPLAIN.
+
+Generic `jonathanong/no-mistakes` checks include `postgres-no-offset`; inspect available rules
+and configure reviewed cross-partition exceptions rather than treating a rule as plan evidence.

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -9,6 +9,9 @@ Read applicable `AGENTS.md` and their declared adapter alias, otherwise
 `.agents/skills/postgres-partitioning-uuid-v7/SKILL.md` from the repository root if present.
 Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
 
+For schema names, references, and canonical table shapes, read
+[postgres-schema-design](../postgres-schema-design/SKILL.md).
+
 Partition only after lifecycle, retention, and query predicates show that it helps.
 
 - Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.

package/skills/postgres-schema-design/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: postgres-schema-design
+description: Design PostgreSQL names, relations, history, work queues, and cursors.
+---
+
+# PostgreSQL schema design
+
+Read applicable `AGENTS.md` and the repository's local database adapter when present.
+Local policy overrides these portable conventions.
+
+- Names explain the stored thing; read [naming](references/naming.md) when naming schema objects.
+- Columns say their type and FK target; finite sets use enums or lookup tables.
+- Joined identities use foreign keys; read [relations](references/relations.md) before modeling references.
+- Split differing shapes, share identical values, and keep history documents as JSON.
+- Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
+- Reuse parameterized trigger functions instead of copying bodies.
+- Comment every table, column, and view; document reviewed exceptions explicitly.
+
+For query shape, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
+For partition lifecycle, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
+Consumer policy owns lifecycle, retention, migration strategy, and enforcement configuration.

package/skills/postgres-schema-design/references/naming.md

@@ -0,0 +1,34 @@
+# Naming
+
+Use full words in snake_case. Tables read as `<owner>_<thing>s`, with only the last word
+plural: `account_payment_methods`, not `accounts_payments_methods`. Core entities may use one
+word (`accounts`, `orders`, `invoices`) when local policy permits it. Enum names follow the same
+plural convention. Choose a shorter full-word name when a base identifier would exceed 63 bytes.
+
+Indexes use `idx_<table>__<suffix>`; a unique index may use `uq_`. The suffix describes its
+purpose or keys. The table portion may abbreviate only when it expands unambiguously to the
+indexed table: preserve every word, its order, and separators. Each shortened word keeps its
+first letter and at least three letters in their original order; words of three or fewer letters
+stay whole. `idx_ord_line_itms__invoice_id` can name an index on `order_line_items`.
+Initialisms and dropped words cannot. All identifiers stay within 63 bytes.
+
+Column names and types imply each other:
+
+- `timestamptz` ends in `_at`; dates use `day` or `_on`.
+- Booleans contain a predicate prefix `is_`, `has_`, `can_`, or `should_` at a word boundary.
+- FK columns end in the target's final word, singular: `invoice_id` references `invoices`.
+  Drop redundant owner words when the column's table already supplies them.
+- A column referencing a natural key may use that key's name. A retained identity reference
+  keeps the entity's name even though the retained table ends in `identities`.
+- Reserve `_user_id` and actor `_by_id` for references to users or retained user identities.
+  Adapt the actor convention to the repository's account model; never use an actor suffix for
+  an unrelated FK or an opaque token.
+
+Trigger functions use `fn_<verb>_<what>` with this closed verb list:
+`reject` (raise on invalid writes), `update` (set the current row), `project` (derived state in
+other rows), `create` (companion rows), `lock`, `register`, and `ensure` (retained identity).
+Ordinary functions use a name that explains their return value.
+
+Generic enforcement: `postgres-object-naming`, `postgres-column-naming`, and
+`postgres-identifier-length` in `jonathanong/no-mistakes`. Check the installed rule's supported options before enabling it;
+an upstream rule name does not establish that the installed release includes it.