vouchington-tooling 0.43.0 → 0.45.0

package/docs/mcp-server.md

@@ -82,17 +82,18 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
 server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
 as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
 
-| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                             | Returns                                                                                                                                          |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`       | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
-| `journal_entries`     | none                                                                                                                                                                                     | `sessionId` and `entries`, every entry oldest first                                                                                              |
-| `outbox_status`       | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
-| `outbox_flush`        | none                                                                                                                                                                                     | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
-| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                    | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
-| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                 | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
-| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown` and `policy.warnings`                                                      |
-| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                          | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
-| `session_archive`     | none                                                                                                                                                                                     | `sessionId`, `archived: true`                                                                                                                    |
+| Tool                  | Arguments besides `sessionId` and `worktree`                                                                                                                                                                                                                                                  | Returns                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `journal_append`      | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category`                                                                                                            | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount`          |
+| `journal_entries`     | none                                                                                                                                                                                                                                                                                          | `sessionId` and `entries`, every entry oldest first                                                                                              |
+| `outbox_status`       | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`                                          |
+| `outbox_flush`        | none                                                                                                                                                                                                                                                                                          | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` (when any) |
+| `session_ensure`      | `parentSessionId`, `agent`, `version`                                                                                                                                                                                                                                                         | `sessionId`, `status` (`created` or `exists`), `archived`                                                                                        |
+| `retrospective_check` | optional `sourceEventId`                                                                                                                                                                                                                                                                      | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first)                              |
+| `retrospective_save`  | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings`                                      |
+| `snapshot_export`     | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours`                                                                                                                                                                                               | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken`                                                                            |
+| `snapshot_cleanup`    | `cleanupToken`                                                                                                                                                                                                                                                                                | `sessionId`, `cleaned: true`                                                                                                                     |
+| `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
@@ -146,6 +147,35 @@ outbox does not create the directory. `snapshot_export` never accepts a destinat
 `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.
 
+### Snapshot cleanup
+
+`snapshot_export` writes a private file in the OS temp directory, and `snapshot_cleanup` is the only
+way to delete it through the server. It was chosen over cleanup inside `session_archive` because
+the exporting session and the archived sessions differ during distillation, and cleanup must run
+whether or not archiving happened. Call it as a finally step after processing, on success and on
+failure.
+
+- **No caller-chosen path.** The tool takes only `cleanupToken` (`path`, `directory`, and `receipt`
+  are unsupported arguments). The server records the export's file path itself, plus a partition
+  directory and its signed receipt when the client reports both, and cleans exactly that record.
+  When the client's export carried its own cleanup capability, the server keeps it (never
+  returning it) and cleans through the client's `cleanupSnapshotPartitions`, so the client's
+  ownership marker goes with the file; otherwise it uses the in-tree `cleanupSnapshotPartitions`.
+- **Server-minted, bound token.** `snapshot_export` replaces the client's `cleanupToken` with 32
+  random bytes the server generates, recorded with the caller's `sessionId` and resolved `worktree`.
+  The binding is checked before any filesystem call.
+- **Single use.** A successful cleanup spends the token; a repeat fails as unknown and deletes
+  nothing. The record is taken synchronously, so concurrent calls cannot both clean.
+- **Failure modes.** An unknown, forged (including a path used as a token), spent, other-session, or
+  other-worktree token fails with one message and deletes nothing; a mismatched caller does not spend
+  the owner's token. If the cleanup itself fails, the token stays valid and the error carries the
+  reason, including the retained tombstone path when a partition directory was half removed, so the
+  same call can retry. A file that is already gone counts as cleaned.
+- **Server restart.** Bindings are in memory only. After a restart every earlier token is unknown, so
+  the file is left for the operating system to reap from its temp directory; run the distill pass
+  again to export a fresh snapshot. The registry also remembers at most 256 exports and forgets the
+  oldest first.
+
 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.
 
@@ -168,7 +198,9 @@ instructions shows it to the agent.
 ## Retrospective tools and the policy contract
 
 `retrospective_check` reads the session through the same client as `journal_entries` and reports the
-entries whose envelope `type` is `retrospective`. A session that was never created (the blackboard
+entries whose envelope `type` is `retrospective`. A schema-versioned entry counts only when its
+envelope passes `validateFeedbackEnvelope`; a malformed one is not saved, while an unversioned legacy
+entry is still accepted. A session that was never created (the blackboard
 answers 404) reports `saved: false`.
 
 `retrospective_save` builds a `retrospective` envelope and writes it exactly as `journal_append`
@@ -189,7 +221,20 @@ are killed after 120 seconds. `compose.facts` takes `pr`, `branch`, `noPr`, or `
 worktree's. Facts run `git` and `gh` in the worktree as the server's user, honoring its
 repository configuration (which can select helpers that run code), so the worktree, including
 `.git/config`, must be as trusted as the policy module. `dryRun`
-runs every check and returns the document without writing.
+runs every check and returns the document without writing, plus a `previewToken`.
+
+`knownSensitiveValues` (each at least 4 characters) is also accepted beside `markdown`, and
+redacts the markdown, `category` and `feedbackCoverage` just as `compose.knownSensitiveValues`
+does; with `compose`, pass it inside `compose`. The `previewToken` is 32 random bytes (base64url),
+opaque, single use, and held only in server memory: a restart drops every token, and the registry
+keeps the 32 most recent. It is bound to the `sessionId`, `parentSessionId`, `mode`, the resolved worktree, the `sourceEventId`
+and the exact redacted content. Save it by calling `retrospective_save` again with the identity,
+the same `parentSessionId`, `mode`, `sourceEventId` and `previewToken`, and none of `markdown`, `compose`,
+`workOutcome`, `feedbackCoverage`, `repositories`, `category`, `knownSensitiveValues` or `dryRun`.
+The server stores exactly the previewed content (so a sensitive value never has to be sent
+again), mints a new timestamp, and does not run the policy again. An unknown, spent, restarted or
+mismatched token is one error and the dry run must be repeated; a mismatch does not spend the
+token, and neither does a failed write.
 
 The document must open with the front matter `composeRetrospective` writes: lines of
 `key: <JSON value>` between two `---` lines. Recognized keys are `date`, `issues`, `prs` (required),
@@ -229,7 +274,7 @@ whole process group is killed, so nothing it started outlives the call. The runn
 | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------- |
 | `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   |
+| `validatePullRequest`   | `title`, `body`, `base`, `head`, the trusted `mode`, `noSourceIssue` when given, and `pr` when set                                                                          | `{ 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
@@ -241,9 +286,33 @@ shape is an error, never a pass.
 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`.
+(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), optional `noSourceIssue`
+(`{ reason }`, see below), `details` (string array), `base` (default `main`), `agent`, optional
+`model`, optional `mode` (`interactive` | `autonomous`) and `workspaceSetup`. `pr_update` also
+requires `pr`; `pr_validate` accepts an optional `pr`.
+
+### Trusted mode
+
+The mode the policy sees is derived by the server from its own launch environment, never from the
+caller. It fails closed: when any automation marker is set to something other than an empty
+string, `0` or `false` (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`,
+`JENKINS_URL`, `TF_BUILD`, `CODEBUILD_BUILD_ID`, `VOUCHINGTON_AUTOMATION`), the mode is
+`autonomous` whatever the caller passes. `CLAUDE_CODE_SESSION_ATTENDED` set to exactly `0` (Claude
+Code's marker for an unattended `claude -p` run, inherited by MCP servers) also means `autonomous`;
+a missing value or `1` never does. This list is a superset of the downstream check it replaces,
+which was exactly `GITHUB_ACTIONS === 'true' || CI === 'true'`. Otherwise the mode is `interactive`. The optional `mode`
+argument can only narrow `interactive` to `autonomous` (it never widens), so an autonomous run
+cannot unlock an interactive-only policy exception. The policy child receives no env markers, so it
+relies on this value.
+
+### Pull requests with no source issue
+
+Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`; a non-empty
+`relatedIssues` beside it is rejected. The Related issues section then holds the generic statement
+`- No source issue — <reason>` instead of `- None`. A policy may replace the statement by
+exporting `renderNoSourceIssue({ reason })`, returning a non-empty string (30 s). The field also
+reaches `validatePullRequest` (with the trusted `mode`, so the policy can apply an interactive-only
+rule) and `pullRequestDefaults`.
 
 ### Rendering
 
@@ -258,7 +327,8 @@ input: `title` (single line, at most 256 characters), `summary`, `impact`, `rela
 
 ## Related issues
 
-- Closes #N — <reason>      (or "Refs #N"; "- None" when empty)
+- Closes #N — <reason>      (or "Refs #N"; "- None" when empty;
+                             "- No source issue — <reason>" for noSourceIssue)
 
 ## Details
 
@@ -270,18 +340,20 @@ 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,
+The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
+request's head, which may equal `base` for a fork); otherwise 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`.
+  base, head, mode, noSourceIssue?, 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`. The liveness checks of `pr_update` do not apply: any state (merged or closed
+  included) and any head are accepted, and the policy sees the pull request's own head and base.
 - `pr_create` (additive): renders and validates (errors block), then calls the policy
-  `pullRequestDefaults({ title, base, relatedIssues })` export for optional `labels`, `milestone`
+  `pullRequestDefaults({ title, base, relatedIssues, noSourceIssue? })` 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 }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.43.0",
+  "version": "0.45.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",
@@ -376,13 +391,13 @@
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@ast-grep/cli": "0.45.3",
-    "@modelcontextprotocol/sdk": "1.32.0",
+    "@ast-grep/cli": "0.50.0",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.1",
     "no-mistakes": "0.83.0",
-    "smol-toml": "1.9.0",
+    "smol-toml": "1.9.1",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {

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