vouchington-tooling 0.25.0 → 0.27.0

package/docs/mcp-server.md

@@ -42,25 +42,52 @@ 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                                                                                                                                                                                            | the session's entries as markdown                                                               |
-| `outbox_status`   | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`                                                           |
-| `outbox_flush`    | none                                                                                                                                                                                            | `sessionId`, `status`, `pendingCount`, `deliveredCount`                                         |
-| `session_ensure`  | `parentSessionId`, `agent`, `version`                                                                                                                                                           | `sessionId`, `status` (`created` or `exists`), `archived`                                       |
-| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                 | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                           |
-| `session_archive` | none                                                                                                                                                                                            | `sessionId`, `archived: true`                                                                   |
+| 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
+`repositories`, `sourceEventId`, `workOutcome`, and `feedbackCoverage`. Entries of every type come
+back, including `retrospective` and legacy entries without an envelope. The client documents no
+order, so they are sorted stably by `createdAt`, oldest first. An empty session returns
+`entries: []`. `vouchington agent-blackboard journal entries` still prints journal markdown only.
 
 `sessionId` on `outbox_status`, `outbox_flush`, and `snapshot_export` only identifies the caller.
-The outbox is per worktree and the status and flush cover every record in it. Flushing an empty
+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.
@@ -68,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
@@ -112,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
@@ -119,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.25.0",
+  "version": "0.27.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/blackboard/SKILL.md

@@ -13,38 +13,85 @@ Use when the current repository provides a journal, blackboard, or equivalent du
 record. Read local `AGENTS.md` for the provider, credential, retention, and
 subagent-identity rules.
 
+Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
+`journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `session_ensure`,
+`snapshot_export`, and `session_archive`. 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 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.
+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
    findings. Record useful resolved outcomes as well as unresolved gaps. Include bounded evidence,
    affected areas, an explicit disposition, and an existing tracking reference when present.
    Journal meaningful skips or bypasses of applicable configured workflows before completion, with
    the owning workflow or command-catalog entrypoint, reason, and observed result/action.
-2. Use the shared validated envelope with storage `type: journal` or `retrospective`, canonical exact
-   entry repositories, stable `sourceEventId`, work outcome, and explicit feedback coverage. Category
-   is optional context; it never changes storage type or distillation eligibility. Generate routine
-   facts and metadata through the approved composer instead of hand-authoring factual markers.
+2. Record each observation with one `journal_append` call and pass the note as its `markdown`
+   argument (at most 12000 bytes). Required arguments are `sessionId`, `parentSessionId` (null for a
+   root session), `agent`, `version`, `mode`, `markdown`, a stable `sourceEventId`, `workOutcome`,
+   canonical exact `repositories`, and explicit `feedbackCoverage`. 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`.
 3. Preserve exact provider session and parent identities. Each agent writes only its own session.
-   Update that session's cumulative repository union before appending; never infer another repository
-   from prose or create a child identity from a model guess.
-4. Select the repository's trusted mode explicitly. Interactive outages may retain validated,
-   sanitized feedback in the bounded durable outbox. Report pending count and delivery state, replay
-   with the same source identity, and continue primary work only after persistence succeeds. A full,
-   unsafe, or unwritable outbox blocks capture; never evict or silently discard an unsent record.
-5. Autonomous runners require online session ensure, a fresh admission write, and readback before
-   launching an attempt. Terminal reporting preserves work outcome separately from feedback
-   coverage and delivery. A filesystem outbox never grants admission or acknowledged completion.
-6. Use at-least-once delivery with consumer deduplication by exact session/source identity. A
-   transport timeout can leave a late durable write; pending or blocked is never an acknowledged
-   receipt. Replay verifies matching content before retrying and rejects conflicting source reuse.
-7. Read journal entries oldest-first for retrospectives. Record explicit none-observed with inspected
-   scope, or not-assessed/unavailable with reason, when evidence does not establish a finding. A
-   permission request is not proof of approval or denial; localhost refusal is not proof of sandbox
-   enforcement. Mark partial capture and dropped counts instead of reporting clean evidence.
+   `journal_append` ensures that session and merges the entry's `repositories` into the session's
+   cumulative repository union, so list every repository the entry concerns. Never infer another
+   repository from prose or create a child identity from a model guess. Call `session_ensure` with
+   the exact identity only when a runner must confirm the session before work starts.
+4. Select the repository's trusted `mode` (`interactive` or `autonomous`) explicitly. In interactive
+   mode an outage may retain the validated, sanitized record in the bounded durable outbox, and
+   `journal_append` reports it as pending. Report `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
+   prove a fresh write. Autonomous mode has no filesystem outbox, so a failed delivery is an error.
+   Terminal reporting preserves work outcome separately from feedback coverage and delivery. A
+   filesystem outbox never grants admission or acknowledged completion.
+6. Use at-least-once delivery with consumer deduplication by exact session/source identity. To
+   retry a pending or failed append, 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
+   find an existing retrospective and keep entry-level tags. Record explicit
+   none-observed with inspected scope, or not-assessed/unavailable with reason, when evidence does
+   not establish a finding. A permission request is not proof of approval or denial; localhost
+   refusal is not proof of sandbox enforcement. Mark partial capture and dropped counts instead of
+   reporting clean evidence.
 
 Never search for, print, invent, or mint credentials. Durable entries and outbox records contain only
 bounded structured facts or sanitized summaries, never raw command output, transcript content,
 environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's
 minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.
 
-Consumer wrappers own service configuration, trusted mode selection, commands, outbox location,
-issue routing, and archival authorization.
+Consumer wrappers own service configuration, server registration and approval rules, trusted mode
+selection, issue routing, and archival authorization. The server fixes the outbox location.

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.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.9.0",
+      "pluginVersion": "0.11.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.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.9.0",
+      "pluginVersion": "0.11.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -70,26 +70,26 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "organize-github-issues/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.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.9.0",
+      "pluginVersion": "0.11.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "retrospective-distill/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.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.9.0",
+      "pluginVersion": "0.11.0",
       "path": "review-github-issue-taxonomy/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "revisit-followups/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.0",
+      "pluginVersion": "0.11.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.9.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.

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

@@ -0,0 +1,46 @@
+# Relations
+
+An identity that readers join is an FK column or an FK child row. JSON holds structured,
+schemaless data and history snapshots, including identities recorded as they were at the time.
+Do not use UUID arrays, JSON ids, or type/id pairs for live relations. A column never names a
+table: use one table per target and generate any per-relation progress enum from the same metadata.
+Cursor positions and random fencing tokens are intentionally not live entity references; record
+their reviewed exception instead of inventing a foreign key.
+
+Split tables when their columns or FK targets differ; share a table when only a value differs.
+Identical lookup values share a row without a source discriminator. Put subtype-only columns in
+a subtype table whose primary key also references the base row (`business_accounts.account_id`
+references `accounts.id`). A 1:N child remains an ordinary child table.
+
+For one of several sources, use an exclusive arc:
+
+```sql
+CHECK (num_nonnulls(order_id, invoice_id) = 1)
+```
+
+Both source columns have their own FK. If a reference must belong to the same account, enforce
+`FOREIGN KEY (account_id, invoice_id) REFERENCES invoices (account_id, id)` with a corresponding
+unique key on the target. A validation trigger is unnecessary. With nullable `invoice_id`,
+default `MATCH SIMPLE` skips that composite check when the reference is absent.
+
+A ledger that survives deletion references a retained identity row with explicit deletion
+behavior. Retained identities preserve history; they do not authorize operations on a deleted
+account, order, or invoice. Index FK columns with a leading key usable by referential checks.
+
+Finite code-defined values use enums. Use a lookup table when values carry attributes or arrive
+at runtime. Authenticated vendor-defined values are inserted into a shared lookup on first sight,
+with validation and concurrent insertion handled explicitly. Do not let untrusted strangers
+create unbounded permanent lookup rows; reviewed raw text can be appropriate for their input.
+Free text and a lookup's own natural key are not finite sets.
+
+Arrays are for enums or outside-defined lists; live identity collections use FK child rows,
+never `uuid[]`. User-submitted URLs go through one registry with centralized normalization and
+validation, then use URL FKs. Keep exact external protocol identifiers, capability URLs, and
+evidence snapshots unchanged when their contract requires it; document the exception.
+Do not duplicate a child collection into a parent column unless a trigger maintains the projection.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-column-naming`,
+`postgres-array-columns`, `postgres-table-shape`, `postgres-fk-index`, and
+`postgres-require-fk-on-delete`. These cover naming, configured shapes, and FK mechanics;
+inspect the installed rule versions and options rather than assuming complete semantic coverage.
+Comments and reviewed exceptions remain necessary.

package/skills/postgres-schema-design/references/table-shapes.md

@@ -0,0 +1,56 @@
+# Table shapes
+
+Choose a shape by lifecycle and meaning. Do not store hand-synchronized status beside lifecycle
+timestamps. A final lifecycle derives enum status with an immutable generated expression over
+timestamps such as `claimed_at`, `completed_at`, and `failed_at`. A time-based expiry needs an
+explicit sweeper-written timestamp; `now()` cannot appear in an immutable generated expression.
+When state keeps returning to earlier states, record append-only attempts or changes and derive
+current state from the latest row rather than erasing the previous lifecycle.
+
+| Concept                    | Shape                                                                                                                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Field-diff history         | `<entity>_revisions`: UUIDv7 `id`, entity FK, nullable revision actor FK with `ON DELETE SET NULL`, revision-type enum, `changes jsonb`.                                                   |
+| Typed lifecycle ledger     | `<entity>_changes`: UUIDv7 `id`, entity FK, change-type enum, retained actor identity FK with `ON DELETE RESTRICT`, typed joined payload and JSON for unjoined data. Time comes from `id`. |
+| Current state from a log   | Latest change by `id DESC`, projected through a shared trigger or read through a view.                                                                                                     |
+| Per-entity work            | `<entity>_<job>_work_items`: entity FK, lease and final-outcome columns, claim index, retention.                                                                                           |
+| Job progress               | `<job>_cursors`: finite enum key or checked singleton, keyset positions without FKs, optional sweep upper bound.                                                                           |
+| Inbound or protocol events | Append-only `<source>_events` with `occurred_at` recording the event's business time.                                                                                                      |
+
+Revisions and changes are append-only through a generic `fn_reject_mutation`, parameterized by
+actor columns that may be erased to NULL. Permit only those erasures; parent-cascade deletion
+may be permitted by policy. A trigger-depth test alone cannot prove a delete came from a parent
+cascade, because another trigger also increases depth. Do not copy the parent into each ledger
+row. Keep historical before/after snapshots as JSON rather than joined history child tables.
+A system change has a NULL actor. Retained actors remain historical identities, without authority.
+
+## Work leases
+
+The lease lives on a row that exists only for the work. If an invoice outlives a delivery job,
+use `invoice_delivery_work_items`, with an invoice FK and `ON DELETE CASCADE`, rather than putting
+the lease on the invoice. Do not create a shared polymorphic lease table.
+
+Use `lease_token uuid`, `leased_at`, `lease_expires_at`, `attempt_count`, `available_at`, and
+`completed_at` plus timestamps for final outcomes. Add `generation` only when re-enqueue can race
+a running worker. Each claim or reclaim gets a fresh opaque token. Every renewal, completion,
+and failure must include `WHERE lease_token = $mine`; zero affected rows means ownership was lost.
+Keep retries in an optional `_attempts` ledger with `attempt_number` when their lifecycle must
+survive. One-shot compare-and-set claims and human assignments need their own shapes.
+
+## Cursors and shared functions
+
+A cursor key names the finite thing being swept. A singleton uses
+`is_singleton boolean PRIMARY KEY DEFAULT true CHECK (is_singleton)`; the job seeds its own row
+with `ON CONFLICT DO NOTHING`. `cursor_<thing>_id` and optional `sweep_upper_bound_<thing>_id` are
+FK-free UUIDv7 positions; NULL means the start. Per-unit work progress belongs in work items.
+A UUIDv7 is assigned at insert, not commit: jobs that must see every committed row re-scan an
+overlap rather than assuming an id high-water mark proves commit order.
+
+Use `updated_at` only for mutable rows, always maintained by its trigger; application code never
+writes it. Comment every table, column, and view, including generated objects. Self-explanatory
+columns may have explicit reviewed local exceptions; view comments describe their reader boundary.
+Reuse generic trigger functions with `TG_ARGV` and `TG_TABLE_NAME`; quote dynamic identifiers
+with `format('%I', ...)`. A trigger function and a SQL-callable helper are separate functions.
+
+Generic enforcement in `jonathanong/no-mistakes`: `postgres-table-shape` and
+`postgres-duplicate-function-body`. Configure canonical shapes explicitly and verify which
+rules the installed release supports; lifecycle and authority decisions still need review.