vouchington-tooling 0.42.0 → 0.44.0

package/dist/retrospective-distill/shape.mjs

@@ -0,0 +1,111 @@
+import { isDeepStrictEqual } from 'node:util';
+import { validateFeedbackEnvelope } from "../agent-blackboard/index.mjs";
+import { isCheckpointEntry } from "./checkpoint-entry.mjs";
+import { isRetrospectiveEntry } from "./retrospective-entry.mjs";
+function quarantineReason(entry) {
+    if (entry.data.type !== 'journal' && entry.data.type !== 'retrospective')
+        return 'unknown-entry-type';
+    if (entry.data.schemaVersion !== undefined) {
+        try {
+            validateFeedbackEnvelope(entry.data);
+        }
+        catch {
+            return 'invalid-feedback-envelope';
+        }
+    }
+    return undefined;
+}
+function hasUnresolvedType(entry) {
+    return quarantineReason(entry) !== undefined;
+}
+function classifyShape(session, entries) {
+    if (entries.some(hasUnresolvedType))
+        return 'entry-type-unresolved';
+    if (entries.some(isRetrospectiveEntry))
+        return 'retrospective';
+    if (entries.length === 0) {
+        // Loose equality on purpose: a partition record missing `parentSessionId` entirely (the reader
+        // trusts the file on disk and does not re-validate every field against the Session interface —
+        // see partition-records.mts) must fall to zero-entry-root. This is a topology and capture-gap
+        // signal, never evidence of crash or clean completion. `=== null` would silently misroute
+        // `undefined` into the wrong, discarded bucket.
+        return session.parentSessionId == null ? 'zero-entry-root' : 'zero-entry-child';
+    }
+    return entries.every(isCheckpointEntry) ? 'checkpoint-only' : 'journal-only';
+}
+function newestRetrospectiveAt(entries) {
+    let newest;
+    for (const entry of entries) {
+        if (!isRetrospectiveEntry(entry))
+            continue;
+        if (newest === undefined || Date.parse(entry.createdAt) > Date.parse(newest))
+            newest = entry.createdAt;
+    }
+    return newest;
+}
+// Eligibility rule:
+// (has a retrospective entry AND retroAt < retroCutoff) OR (lastActive < sessionCutoff).
+// An entry-type-unresolved session gets no issue-filing or archival pass "this run, regardless of
+// its age", so it is never eligible — that check short-circuits before the formula.
+function isEligible(session, entries, shape, cutoffs) {
+    if (shape === 'entry-type-unresolved')
+        return false;
+    const retroAt = newestRetrospectiveAt(entries);
+    const staleRetro = retroAt !== undefined && Date.parse(retroAt) < Date.parse(cutoffs.retroCutoff);
+    const lastActive = entries.reduce((latest, entry) => Date.parse(entry.createdAt) > Date.parse(latest) ? entry.createdAt : latest, session.createdAt);
+    const staleSession = Date.parse(lastActive) < Date.parse(cutoffs.sessionCutoff);
+    return staleRetro || staleSession;
+}
+// An event is its session, `sourceEventId`, and content; the server assigns `timestamp` per attempt
+// (a retry or a late write beside it can store the same event twice), so it is not identity.
+function withoutTimestamp(data) {
+    return Object.fromEntries(Object.entries(data).filter(([key]) => key !== 'timestamp'));
+}
+function normalizeSourceEvents(entries) {
+    const events = new Map();
+    const unique = [];
+    let duplicateEntryCount = 0;
+    let conflictCount = 0;
+    for (const entry of entries) {
+        if (entry.data.schemaVersion !== 1 || quarantineReason(entry) !== undefined) {
+            unique.push(entry);
+            continue;
+        }
+        const key = `${entry.sessionId}:${String(entry.data.sourceEventId)}`;
+        const existing = events.get(key);
+        if (!existing) {
+            events.set(key, entry);
+            unique.push(entry);
+            continue;
+        }
+        if (!isDeepStrictEqual(withoutTimestamp(existing.data), withoutTimestamp(entry.data))) {
+            conflictCount++;
+            continue;
+        }
+        duplicateEntryCount++;
+        // At-least-once replay does not postpone a source event's distillation age.
+        if (Date.parse(entry.createdAt) < Date.parse(existing.createdAt)) {
+            unique[unique.indexOf(existing)] = entry;
+            events.set(key, entry);
+        }
+    }
+    return { unique, duplicateEntryCount, conflictCount };
+}
+export function classifySession(session, entries, cutoffs) {
+    const { unique, duplicateEntryCount, conflictCount } = normalizeSourceEvents(entries);
+    const shape = conflictCount ? 'entry-type-unresolved' : classifyShape(session, unique);
+    const reasons = entries
+        .map(quarantineReason)
+        .filter((reason) => reason !== undefined);
+    for (let index = 0; index < conflictCount; index++)
+        reasons.push('conflicting-source-event');
+    return {
+        sessionId: session.id,
+        shape,
+        eligible: isEligible(session, unique, shape, cutoffs),
+        ...(duplicateEntryCount ? { duplicateEntryCount } : {}),
+        ...(reasons.length === 0
+            ? {}
+            : { quarantine: { entryCount: reasons.length, reasons: [...new Set(reasons)].toSorted() } }),
+    };
+}

package/docs/mcp-server.md

@@ -7,7 +7,7 @@ existing `vouchington-tooling/agent-blackboard` exports and adds no provider pro
 
 Phase 1 of [vouchington-tooling#324](https://github.com/vouchington/vouchington-tooling/issues/324)
 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.
+and the policy contract they run. Phase 3 adds the pull request tools.
 
 ## Install
 
@@ -225,16 +225,90 @@ whole process group is killed, so nothing it started outlives the call. The runn
 `{ 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   |
+| Export                  | Input                                                                                                                                                                       | Result                                                         | Timeout |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
+| `validateRetrospective` | `sessionId`, `parentSessionId`, `mode`, `workOutcome`, `feedbackCoverage`, `repositories`, `markdown`, `sourceEventId`, `metadata` (`date`, `issues`, `prs`, `description`) | `{ errors: string[], warnings?: string[] }`                    | 30 s    |
+| `pullRequestDefaults`   | `{}` from `retrospective_save`; `{ title, base, relatedIssues }` from `pr_create`                                                                                           | `{ repositories?, labels?, milestone?, project? }` (an object) | 120 s   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, `mode`, and `pr` for an update                                                                                                             | `{ errors: string[], warnings?: string[] }`                    | 120 s   |
 
 Any `errors` reject the save and write nothing. A non-zero exit, a timeout (reported as
 `policy <export> timed out after <N>s`), output over 1 MB, malformed JSON, or a result of the wrong
 shape is an error, never a pass.
 
+## Pull request tools
+
+`vouchington mcp` serves `pr_validate`, `pr_create` and `pr_update` besides the journal and
+retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
+launched inside a repository worktree (they run the checkout policy), and share this structured
+input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), `details` (string array),
+`base` (default `main`), `agent`, optional `model`, `mode` (`interactive` | `autonomous`) and
+`workspaceSetup`. `pr_update` also requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Rendering
+
+```
+## Summary
+
+<summary>
+
+## Impact
+
+<impact>
+
+## Related issues
+
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+
+## Details
+
+<details joined by blank lines>
+
+Workspace setup: <workspaceSetup>
+Agent: <agent>[ (<model>)] session <sessionId>
+Device: <os user>@<lowercased hostname>
+Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
+```
+
+The head branch is the worktree's current branch; a detached HEAD, or a head equal to `base`, is
+rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
+so a consumer policy may reject any `base` other than the default branch; create stacked layers
+with the repository's stack tooling instead.
+
+### Tools
+
+- `pr_validate` (read-only): renders the body, runs the policy `validatePullRequest({ title, body,
+  base, head, mode, pr? })` export and returns `{ body, errors, warnings }`. With `pr`, the live
+  body is read (never written) so its Shepherd Journal is preserved as in `pr_update`.
+- `pr_create` (additive): renders and validates (errors block), then calls the policy
+  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  and `project`. It checks the head is pushed and current, writes the body to a mode 0600 temp file
+  (removed afterwards) and runs `gh pr create --draft` with the labels, `--milestone` and
+  `--project`. Returns `{ number, url, warnings }`.
+- `pr_update` (mutating): reads `gh pr view <pr> --json body,headRefName,baseRefName,state`,
+  rejects a pull request that is not `OPEN` or whose head is not the worktree branch, and validates
+  against the live base (an explicit `base` must equal it). It renders, appends the live Shepherd
+  Journal (a `<details><summary>Shepherd Journal</summary>` block, or a legacy `## Shepherd Journal`
+  section to the next H2 or the end; examples in fenced code blocks are ignored), validates with
+  `pr` set (errors block), then runs `gh pr edit <pr> --title --body-file`. More than one journal
+  in the live body, one in the rendered fields, an unclosed journal, or rendered fields that leave
+  a code fence open are rejected rather than guessed. Just before the edit the live body is read
+  again, and the update aborts if its journal changed meanwhile. Nothing else is carried over from
+  the live body. Returns `{ number, url, warnings }`.
+
+Every field is redacted of `AGENT_BLACKBOARD_TOKEN`, `GH_TOKEN`, and `GITHUB_TOKEN` before
+rendering, the policy, or `gh`; a worktree branch name containing one is rejected. `title` and
+`workspaceSetup` must be single lines, and the title is limited to 256 characters after redaction.
+
+### gh access
+
+`gh` is found in the absolute directories of the server's `PATH` (relative entries are skipped,
+since they would resolve inside the target worktree), else at `/opt/homebrew/bin/gh`, `/usr/local/bin/gh` or
+`/usr/bin/gh`; otherwise the tool fails with "gh CLI not found on PATH; install gh or add it to the
+server's PATH". It runs with the worktree as its working directory and the server environment
+without `AGENT_BLACKBOARD_URL`, `AGENT_BLACKBOARD_TOKEN`, and `GH_REPO` (which would point it at
+another repository), and each call is killed after 120 seconds.
+
 ## Worktree validation
 
 `worktree` is checked on every call. It must be an absolute path that, after resolving symlinks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -101,6 +101,11 @@
       "import": "./dist/require-up-to-date/index.mjs",
       "default": "./dist/require-up-to-date/index.mjs"
     },
+    "./fresh-base": {
+      "types": "./dist/fresh-base/index.d.mts",
+      "import": "./dist/fresh-base/index.mjs",
+      "default": "./dist/fresh-base/index.mjs"
+    },
     "./gitleaks-directory-scan": {
       "types": "./dist/gitleaks-directory-scan/index.d.mts",
       "import": "./dist/gitleaks-directory-scan/index.mjs",
@@ -136,6 +141,11 @@
       "import": "./dist/shared-context/index.mjs",
       "default": "./dist/shared-context/index.mjs"
     },
+    "./retrospective-distill": {
+      "types": "./dist/retrospective-distill/index.d.mts",
+      "import": "./dist/retrospective-distill/index.mjs",
+      "default": "./dist/retrospective-distill/index.mjs"
+    },
     "./source-module-graph": {
       "types": "./dist/source-module-graph/index.d.mts",
       "import": "./dist/source-module-graph/index.mjs",
@@ -321,6 +331,11 @@
       "import": "./dist/compiler-build/index.mjs",
       "default": "./dist/compiler-build/index.mjs"
     },
+    "./pull-request-diff": {
+      "types": "./dist/pull-request-diff/index.d.mts",
+      "import": "./dist/pull-request-diff/index.mjs",
+      "default": "./dist/pull-request-diff/index.mjs"
+    },
     "./github-projects": {
       "types": "./dist/github-projects/index.d.mts",
       "import": "./dist/github-projects/index.mjs",
@@ -364,7 +379,7 @@
   "dependencies": {
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
-    "@typescript-eslint/parser": "^8.71.0",
+    "@typescript-eslint/parser": "^8.71.1",
     "csv-parse": "7.0.3",
     "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
@@ -377,7 +392,7 @@
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
-    "@modelcontextprotocol/sdk": "1.32.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",

package/skills/agent-workflow/SKILL.md

@@ -22,10 +22,30 @@ evidence record.
 - Before handoff, use [evidence sweep](references/evidence-sweep.md).
 - For review, use [review](references/review.md).
 - For surfaced feedback, use [review response](references/review-response.md).
+- Before any rebase or lease push, use [four refs](references/four-refs.md).
 
 Load only the references required by the current phase. Keep scope changes explicit; a discovered
 blocker or follow-up does not authorize widening the task.
 
+## Close-out
+
+This section is the single home for the hand-off retrospective and merge-note rules.
+
+- Report actual validation, open pull requests, and remaining blockers.
+- **Hand-off retrospective.** When you hand a pull request to the human as ready, write one
+  [retrospective](../retrospective/SKILL.md) from the session that did the work, which reads that
+  session's transcripts and journal. A native stack gets one retrospective when the stack is handed
+  off, covering every layer; never one per layer or for an intermediate commit.
+- Give each hand-off its own `sourceEventId`, such as `handoff-pr<number>` (a stack uses its top
+  pull request's number), on both `retrospective_check` and `retrospective_save`. The default ID
+  fits only the first hand-off in a session; a second would be mistaken for it.
+- **Merge note.** If you are still running when the merge happens and it changes the outcome, such
+  as a merge-queue ejection and its fix, a follow-up push, or review comments addressed after
+  hand-off, append one short note with the [blackboard skill](../blackboard/SKILL.md). Name the
+  pull request and the retrospective's source event, and give the note its own `sourceEventId` (for
+  example `merge-pr<number>`): the writer rejects the retrospective's ID reused for different
+  content. Never write a second retrospective.
+
 ## Parallel by default
 
 Split work into independent units and run them concurrently, one worker and worktree each, within

package/skills/agent-workflow/references/four-refs.md

@@ -0,0 +1,74 @@
+# Reading the four refs
+
+Use before any rebase or lease push of a branch other agents or humans may also write. Publish this
+branch; do not open a replacement pull request.
+
+`origin` and `main` below stand for the consumer's remote and default branch; substitute the names
+local policy declares.
+
+## Setup
+
+- Run `git fetch origin main <branch>` as its own command. Never chain the fetch with a rebase,
+  reset, or merge.
+- HEAD must be the branch being updated. A stack checkout can leave the top layer checked out, so
+  check out the layer first. A missing stack field means membership is unknown, not unstacked.
+- A dirty worktree stops you before a fast-forward, reset, or rebase. Do not switch branches.
+- Continue a conflicted rebase with `GIT_EDITOR=true git rebase --continue`.
+
+## Read the refs
+
+- Print `git rev-parse` of HEAD, `origin/<branch>`, `origin/main`, and local `main` when it exists.
+  Local `main` is never the rebase target; when it exists, `git rev-list --left-right --count
+  main...origin/main` with a nonzero right count means local `main` is behind.
+- Print `git rev-list --left-right --count HEAD...origin/<branch>` (left: commits only on the
+  local branch; right: commits only on `origin/<branch>`) and
+  `git log --oneline --left-right HEAD...origin/<branch>`.
+- Print `git cherry -v origin/<branch> HEAD` and `git cherry -v HEAD origin/<branch>`. A leading `-`
+  is the same patch under another SHA; a leading `+` is a patch the other side lacks.
+- Treat `git range-diff` as a reading aid, not the rebase cut, and read it from the base those
+  commits were built on. Never run it from a new stack parent: after a stack rebase, old parent
+  commits look like unique local work.
+- Unmatched commits on `origin/<branch>` are new commits someone pushed.
+
+## Lease push
+
+- Capture `<sha>` with `git rev-parse origin/<branch>` after the fetch and before any rewrite. Push
+  a non-fast-forward with `git push --force-with-lease=<branch>:<sha> origin <branch>`, always
+  naming the remote and branch so a configured push remote cannot change the destination. With concurrent writers,
+  capture right after the setup fetch and before any later fetch, so a later fetch cannot silently
+  widen the lease.
+- If HEAD equals that SHA, do not push.
+- If a lease or non-force push is rejected, fetch again and re-read. It is still this branch.
+
+## Unstacked
+
+Before any move and after every move onto `origin/<branch>`, including when HEAD already equals it
+(`0 0`) but `origin/main` has advanced, run `git merge-base --is-ancestor origin/main HEAD`. Exit 0
+means the branch already contains `origin/main`; nonzero means rebase onto `origin/main`, then lease
+push.
+
+| Left/right                                                                                                                                                         | Action                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0 0`, `origin/main` already an ancestor                                                                                                                           | Stop.                                                                                                                                                                                                                                                                                                                                                   |
+| `0 0`, `origin/main` not an ancestor                                                                                                                               | Rebase onto `origin/main`, then lease push.                                                                                                                                                                                                                                                                                                             |
+| `0 N`                                                                                                                                                              | `git merge --ff-only origin/<branch>`, then the ancestor check.                                                                                                                                                                                                                                                                                         |
+| `N 0`                                                                                                                                                              | Read `git log --oneline origin/<branch>..HEAD`: those commits are what a push adds, including a remote rewind to an ancestor. Own unpushed work with `origin/main` an ancestor: `git push origin <branch>`. Otherwise rebase onto `origin/main`, then lease push. A rewind you did not make: stop and ask.                                              |
+| Diverged, local-only commits are rewritten copies (every local-only commit has cherry `-`; matching subjects alone do not prove equivalence), no unique local work | Clean tree, `git reset --hard origin/<branch>`, then the ancestor check.                                                                                                                                                                                                                                                                                |
+| Diverged, origin has new patches to keep and HEAD has unique local commits                                                                                         | `git rebase origin/<branch>` as its own command, then the ancestor check, then lease push whichever way the check exits (after another rebase onto `origin/main` if it is nonzero). This is the one added rebase target, not a license to rebase onto an arbitrary ref. If the rewrite changed patches and unique local work is mixed in, stop and ask. |
+
+## Stacked
+
+A stack rebase is the usual reason `origin/<branch>` was rewritten, but another agent or a human can
+rewrite an unstacked branch the same way.
+
+- On a diverged layer, adopt `origin/<branch>` with `git reset --hard` when the layer is checked
+  out, or `git branch -f` when it is not, if the left-right log shows pre-rebase copies: the same
+  layer subjects on both sides and old parent subjects only on the left. Require `git cherry`
+  patch equivalence (`-`) for every local layer commit first; matching subjects alone do not
+  prove it, and a `+` commit is unique local work.
+- Never `git rebase origin/<branch>` on a stack layer: it replays parent commits onto the layer.
+- Never run the plain rebase-onto-main procedure on a mid-stack branch; use its stack-aware form.
+- If the layer has unpushed commits that are not the old parent and not already on origin under a
+  new SHA, stop and ask.
+- After adopting the rewritten tip, run the stack-aware rebase only when the stack still needs to
+  move onto `origin/main`.

package/skills/blackboard/SKILL.md

@@ -50,7 +50,10 @@ human which case applies before continuing:
   registration and diagnosis steps.
 - Registered but disconnected: reconnect it through the harness's MCP controls, or restart the
   harness.
-- Automated runs with no human to ask: report "journaling unavailable" in the final report.
+- Automated runs with no human to ask: an unattended `interactive` run continues its primary work,
+  while an `autonomous` run keeps its admission gate below. The final report states why journaling
+  was unavailable, the `pendingCount` and `worktreePendingCount` (or that none was written), and
+  each unjournaled finding.
 
 Prefer restoring MCP over the CLI fallback below, and use the fallback only when the human asks or
 MCP cannot be restored for this session. Harness sandboxes commonly withhold
@@ -176,5 +179,22 @@ bounded structured facts or sanitized summaries, never raw command output, trans
 environment dumps, provider payloads, or secrets. Known-secret redaction supplements the author's
 minimization responsibility; it cannot prove arbitrary prose contains no undisclosed secret.
 
+## Credential failures
+
+- Never search shell profiles, `env`, or `.env*` files for a credential. Check presence only with
+  `[ -n "${VAR+x}" ] && echo SET || echo UNSET`; never copy the token around a sandbox denial.
+- A missing or stale credential blocks hosted delivery. In interactive mode the outbox keeps the
+  record visibly pending: do not drop it or invent a fallback. Ask the human to refresh the
+  connection, then restart the MCP client or call `outbox_flush`; an automated run reports.
+
+## Child identity for spawned agents
+
+- Pass the parent's own session id in the assignment prompt. The child resolves its own id from its
+  runtime through the consumer's identity policy, then calls `session_ensure` with it, the given
+  `parentSessionId`, its `agent`, and its version before other work. With no id or a failed ensure,
+  it stops and reports the blocker; never guess an id or pass a path, URL, or synthesized value.
+- A subagent sharing its parent's id must not `session_ensure` it as a child. It asks the parent
+  to append, or skips this protocol.
+
 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/github-issue/SKILL.md

@@ -99,5 +99,11 @@ For a batch, preflight every entry before writing any issue. One invalid entry f
 batch. A partial transport failure stops further creation and reports every issue already created.
 Do not retry an entry that succeeded.
 
+## Bounded output
+
+- A search returns at most five `#N: title -- url` lines.
+- A near-duplicate returns `Duplicate of #N: <url>`.
+- A mutation returns the action, URL, labels, and verification, plus milestone and project when set.
+
 Consumer wrapper owns: repository allowlist, taxonomy, issue template, credential, and CLI wrapper.
 It may tighten this gate and may not weaken it.

package/skills/manifest.json

@@ -6,7 +6,13 @@
       "plugin": "vouchington-workflow",
       "pluginVersion": "0.12.0",
       "path": "agent-workflow/SKILL.md",
-      "prerequisites": ["github-issue", "pr-description", "review-ci-logs"]
+      "prerequisites": [
+        "blackboard",
+        "github-issue",
+        "pr-description",
+        "retrospective",
+        "review-ci-logs"
+      ]
     },
     {
       "name": "backend-vitest-test-authoring",
@@ -24,7 +30,7 @@
     {
       "name": "bounded-iteration",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.6.0",
+      "pluginVersion": "0.7.0",
       "path": "bounded-iteration/SKILL.md"
     },
     {
@@ -109,19 +115,19 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.6.0",
+      "pluginVersion": "0.7.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.6.0",
+      "pluginVersion": "0.7.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
     {
       "name": "postgres-schema-design",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.6.0",
+      "pluginVersion": "0.7.0",
       "path": "postgres-schema-design/SKILL.md"
     },
     {

package/skills/postgres-node-performance-tuning/SKILL.md

@@ -20,6 +20,8 @@ Measure the query plan and the workload shape before changing code.
   connection pressure together.
 - Cut round trips: fold dependent reads, batch per-item lookups, and overlap independent reads; see
   [round trips](references/performance-patterns.md#round-trips).
+- Read the plan for hidden per-row work before trusting a change; see
+  [reading plans](references/reading-plans.md).
 - Read [performance patterns](references/performance-patterns.md) before changing a high-volume
   path.
 

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

@@ -38,6 +38,82 @@ 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.
 
+## Volatile functions in predicates
+
+`uuidv7(interval)` and `random()` are volatile: PostgreSQL evaluates them for every row, so
+`WHERE id >= uuidv7(INTERVAL '-30 days')` is a `Filter`, cannot be an `Index Cond`, and blocks
+partition pruning. Compute the bound once per statement and compare against that. A bind
+parameter works, as does a stable expression such as `now() - INTERVAL '30 days'` fed to a stable
+or immutable bound helper. A stable bound can be an index condition, and a partitioned table
+prunes at executor start. Confirm `Index Cond` and `Subplans Removed` in the plan.
+
+```sql
+-- evaluated per row
+SELECT id FROM events WHERE id >= uuidv7(INTERVAL '-30 days');
+-- bound computed once by the caller
+SELECT id FROM events WHERE id >= $1;
+```
+
+## Function inlining
+
+PostgreSQL inlines a simple scalar SQL function into the calling query, so its body is planned
+with the outer query and its predicates can become index conditions. A SQL function whose body
+contains a subquery (for example `EXISTS`) is never inlined as a scalar call; a set-returning SQL
+function in `FROM` follows a separate inlining path. Functions with `SECURITY DEFINER` or
+a `SET` clause, and PL/pgSQL functions, are not inlined either, nor is a body that is not a single
+simple expression. When the function is not inlined, the plan shows only `fn_x(col)` in a `Filter`
+or output, and none of the queries it runs per row.
+
+```sql
+-- not inlined: the EXISTS runs once per orders row
+CREATE FUNCTION fn_has_events(order_id uuid) RETURNS boolean
+LANGUAGE sql STABLE AS $$ SELECT EXISTS (SELECT 1 FROM events e WHERE e.order_id = $1) $$;
+SELECT id FROM orders WHERE fn_has_events(id);
+-- plannable: write the semi-join in the query
+SELECT o.id FROM orders o WHERE EXISTS (SELECT 1 FROM events e WHERE e.order_id = o.id);
+```
+
+Tell from the plan: a function name in `Filter` or output with no matching scan nodes. Count calls
+with `SET LOCAL track_functions = 'all'` and `pg_stat_xact_user_functions` in the same transaction;
+inlined functions are not counted. See [reading plans](reading-plans.md#opaque-function-calls).
+Put per-row logic in the query as a join or `EXISTS`, or keep the function a plain expression.
+
+## Reading views by key
+
+PostgreSQL expands a view into the calling query, and a simple view lets the outer filter push
+down into its base tables. A view that cannot be flattened (aggregation, `DISTINCT`, `LIMIT`,
+set operations, window functions, volatile target-list expressions, a security barrier) is built
+before a filter on a value it derives (such as an aggregate) applies, and before a sort, page, or
+count over its output. A restriction on a grouping column can still be pushed below an aggregate,
+so let the plan decide. Confirm from the
+plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
+base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
+restriction can reach inside the view. This works for an aggregate or `GROUP BY` view whose key is
+a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
+against the base tables instead. A plain join to the page is a join clause, not a restriction
+inside the view, so the planner can still build the whole aggregate first.
+
+```sql
+-- order_summaries aggregates events, so event_count is built for every order, then filtered
+SELECT * FROM order_summaries WHERE event_count > 3 ORDER BY id LIMIT 50;
+-- choose ids from base tables with an equivalent predicate, then read the view by key
+WITH page AS (
+  SELECT o.id FROM orders o
+  WHERE (SELECT count(*) FROM events e WHERE e.order_id = o.id) > 3
+  ORDER BY o.id LIMIT 50
+)
+SELECT s.id, s.total_cents, s.event_count
+FROM page
+CROSS JOIN LATERAL (
+  SELECT * FROM order_summaries WHERE id = page.id
+) s
+ORDER BY s.id;
+```
+
+Filter and sort on indexed base-table columns, and read only the view columns the page needs.
+Confirm in the plan that the view's inner nodes run with `Actual Loops` equal to the page size and
+read only that page's rows.
+
 ## Round trips
 
 Sequential queries can add network round trips when the client waits between statements, and planning