vouchington-tooling 0.40.0 → 0.42.0

package/skills/blackboard/SKILL.md

@@ -38,18 +38,36 @@ Every call may take `worktree`, the absolute path of a worktree of the current r
 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 or not connected, use the supported CLI fallback below.
-Tell the human that MCP is unavailable and which CLI is being used. Record the fallback reason,
-entrypoint, affected operations, and observed delivery status in the caller's journal before
-continuing primary work. Do not treat a permission denial as tool unavailability or bypass a host
-approval requirement through the CLI. If neither path persists the note, stop and report the blocker.
+unavailable; a deferred harness lists the tool only on request. A tool error is not
+unavailability: act on its message and retry through MCP.
+
+## When the server is unavailable
+
+MCP is the supported journaling path. If the search finds no such tool, stop journaling and tell the
+human which case applies before continuing:
+
+- Not registered: the machine's agent configuration must register it; follow the consumer's
+  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.
+
+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
+`AGENT_BLACKBOARD_TOKEN` from shell commands, so the fallback usually cannot deliver there. Never
+request an unsandboxed run only to obtain the token. When the fallback is used, record its reason,
+entrypoint, affected operations, and observed delivery status in the caller's journal. Do not treat
+a permission denial as tool unavailability or bypass a host approval requirement through the CLI.
+If neither path persists the note, stop and report the blocker.
 
 ## CLI fallback
 
+Deprecated and being phased out: the MCP tools replace it, and retrospective and PR writers are
+moving to MCP tools as well.
+
 Use a trusted machine-installed `vouchington` executable at a verified absolute path outside the
 consumer worktree. Resolve its symlinks and verify the installation's source and version before
-using credentials or requesting an unsandboxed run; its runtime dependencies must also belong to
+using credentials; its runtime dependencies must also belong to
 that trusted installation. The CLI resolves its client relative to its own installation; installing
 `agent-blackboard` only in the consumer worktree is insufficient for CLI fallback. Do not resolve the executable through the consumer's `node_modules/.bin`,
 `pnpm exec`, or repository-controlled `PATH`. Set `BLACKBOARD_CLI` below to that verified absolute
@@ -93,13 +111,9 @@ explicit coverage sources when assessed. Omit `--timestamp` so the writer owns t
 mode omits `--outbox-directory` and still requires fresh online admission plus readback.
 For session-only or snapshot operations not exposed by this CLI, use the upstream
 `agent-blackboard` CLI under its skill's operation contract; preserve exact identities and tags.
-A sandboxed fallback may only write the outbox: the machine's harness sandbox can withhold
-`AGENT_BLACKBOARD_TOKEN`, so it cannot deliver or read back. If delivery or readback needs the
-credentials and the sandbox withholds them, run that one command unsandboxed through the harness's
-normal approval path for running one command outside the sandbox, with each such run approved
-individually. Never read, print, copy, or export the token
-to work around the sandbox. If approval is denied, leave the record pending in the outbox, report
-`pendingCount`, and tell the human.
+A sandboxed fallback may only write the outbox: without `AGENT_BLACKBOARD_TOKEN` it cannot deliver
+or read back. Leave the record pending, report `pendingCount`, and deliver it with `outbox_flush`
+once MCP is restored. Never read, print, copy, or export the token to work around the sandbox.
 Return to MCP when available and journal recovery. Never silently downgrade envelope validation,
 retention, or delivery checks because the transport changed.
 

package/skills/manifest.json

@@ -24,7 +24,7 @@
     {
       "name": "bounded-iteration",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.5.0",
+      "pluginVersion": "0.6.0",
       "path": "bounded-iteration/SKILL.md"
     },
     {
@@ -109,19 +109,19 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.5.0",
+      "pluginVersion": "0.6.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.5.0",
+      "pluginVersion": "0.6.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
     {
       "name": "postgres-schema-design",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.5.0",
+      "pluginVersion": "0.6.0",
       "path": "postgres-schema-design/SKILL.md"
     },
     {

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

@@ -18,6 +18,8 @@ Measure the query plan and the workload shape before changing code.
 - Keep connection-pool usage bounded.
 - Validate a query change at representative cardinality. Watch latency, memory, lock time, and
   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 [performance patterns](references/performance-patterns.md) before changing a high-volume
   path.
 

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

@@ -37,3 +37,26 @@ 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.
+
+## Round trips
+
+Sequential queries can add network round trips when the client waits between statements, and planning
+can add latency when PostgreSQL does not reuse a prepared plan; count round trips per request before
+tuning individual statements.
+
+Load a parent and the viewer's relation to it in one query: join the membership row, or use a
+lateral subquery, rather than reading the parent and then the relation.
+
+`Promise.all` over statements on one transaction client is still serial, because one connection
+runs one statement at a time. Merge them instead: CTEs, `UNNEST`, or one multi-row statement.
+
+Give every per-item lookup helper a batch twin that takes an array of keys and returns a keyed
+map, and call the twin from loops, `.map` callbacks, and `Promise.all` fan-outs. `no-await-in-loop`
+misses a helper that queries internally and `Promise.all(items.map(helper))`; review those call
+sites by hand.
+
+Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rate-limiter check
+alongside the user fetch. Serialize only true dependencies, where one result feeds the next call.
+
+Run a symmetric check, such as "is either party blocking the other", as one query with an `OR`
+or both-direction predicate, not twice with the arguments swapped.

package/skills/retrospective/SKILL.md

@@ -14,7 +14,8 @@ local `AGENTS.md`, and journal guidance first.
 
 1. Read the agent's own journal oldest-first and check for an existing retrospective. Capture a
    material new observation before filing a follow-up issue. Preserve entry-level repository tags.
-2. Generate routine repository and transcript facts with the approved composer. Keep exact factual
+2. Generate routine repository and transcript facts with the approved composer: pass `compose` to
+   the `retrospective_save` MCP tool and preview the composition with `dryRun`, never a CLI. Keep exact factual
    section markers generated, preserve unavailable counts, and never replace missing evidence with
    invented zero statistics. Do not paste raw collectors' output or manually reconstruct facts.
 3. Record work outcome, feedback coverage, and delivery independently. Success, failure,
@@ -30,7 +31,9 @@ local `AGENTS.md`, and journal guidance first.
 5. Keep the top five findings or improvements in the human prose. The bounded durable evidence can
    retain additional relevant findings; a prose limit is not permission to silently discard them.
    Separate recurring root causes from one-off noise and preserve existing issue references.
-6. Save through the shared validated writer. Interactive outages use the approved bounded private
+6. Check for an existing retrospective with the `retrospective_check` MCP tool and save with
+   `retrospective_save`, never a CLI. A revision of changed content needs a new `sourceEventId`.
+   Interactive outages use the approved bounded private
    outbox with visible pending count; failed persistence blocks capture. Autonomous reporting stays
    online and never uses that outbox to authorize an attempt or completion. Report the acknowledged
    record/receipt, or the actual pending/blocked state and next replay action.