vouchington-tooling 0.43.0 → 0.44.0

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

package/skills/postgres-node-performance-tuning/references/reading-plans.md

@@ -0,0 +1,111 @@
+# Reading plans
+
+Run `EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON)` at representative cardinality, in a transaction you
+roll back when the statement writes. `ANALYZE` executes the statement, and a rollback does not
+undo non-transactional effects such as sequence advancement from `nextval()`. Calls that reach
+outside the database (requests, messages) still happen even in a disposable database, so use plain
+`EXPLAIN` for statements that trigger them, or disable the integrations first. A glance at the top node hides most of the problems below;
+walk every node. `VERBOSE` adds each node's `Output` expressions, which is where a select-list
+function call shows. In JSON, `Actual Rows`, `Actual Startup Time`, `Actual Total Time`,
+`Rows Removed by Filter`, `Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` are
+per-loop averages, so multiply each by `Actual Loops` for the total.
+
+## Red flags
+
+### Rows read per row returned
+
+A node that reads far more rows than it passes up is doing hidden work. Compare
+`Actual Rows` x `Actual Loops` with the rows the parent keeps, and read `Rows Removed by Filter`
+`Rows Removed by Join Filter`, and `Rows Removed by Index Recheck` (lossy GiST, BRIN, Bloom, or
+bitmap pages; `Actual Rows` is counted after the recheck), each x `Actual Loops`. Millions removed to return tens means the predicate is not an
+index condition, the index has the wrong leading columns, or a join filters after it multiplies.
+Fix the index or the predicate shape, or filter before joining.
+
+### SubPlans whose loops equal the outer row count
+
+A node with `"Parent Relationship": "SubPlan"` and `Actual Loops` equal to the outer row count
+runs once per outer row. Correlated subqueries in the select list or in a `Filter` look like
+this. The statements inside a non-inlined function do not appear as SubPlans; see opaque function
+calls below. Rewrite as a join, a `LATERAL` with a limit, or a
+set-based aggregate computed once. An uncorrelated `InitPlan` runs once, but check its own time, rows, and buffers: one large scan,
+sort, or expensive call can still dominate the statement.
+
+### `Filter` where an `Index Cond` was expected
+
+An `Index Cond` narrows the index scan; a `Filter` runs on every row the scan returns. If a
+column you expected in `Index Cond` appears in `Filter`, check for a volatile function, a cast or
+function wrapping the column, a type or collation mismatch, or a column outside the index's
+leading keys. See
+[volatile functions in predicates](performance-patterns.md#volatile-functions-in-predicates).
+
+A partitioned parent whose plan lists every child and shows no `Subplans Removed` may not have
+been pruned at plan or executor start. Pruning on an execution-time parameter, such as a value
+from the outer side of a nested loop, keeps every child in the plan; check the children's loops,
+where children pruned every time show `(never executed)`, and children visited only sometimes
+show loops lower than the containing loop count. Constrain the partition key with a constant, a
+parameter, or a once-per-statement stable expression; the bound must not be a volatile call.
+
+### Opaque function calls
+
+A plan shows `fn_x(col)` in a `Filter` or output column and nothing about the queries the
+function runs. A scalar SQL function whose body contains a subquery, such as `EXISTS`, is never inlined,
+so those queries run per row and stay invisible. Count the calls in one transaction:
+
+```sql
+BEGIN;
+SET LOCAL track_functions = 'all';  -- needs superuser or a granted SET privilege
+SELECT count(*) FROM orders WHERE fn_is_visible(orders.id);
+SELECT funcname, calls FROM pg_stat_xact_user_functions;
+ROLLBACK;
+```
+
+A positive call count proves the function was not inlined. Inlined functions are not counted, but
+a missing row is only suggestive: a query that returns no rows or short-circuits the predicate also
+never calls the function, so confirm the function body shape before concluding it was inlined.
+Tested on
+PostgreSQL 18.6: an `EXISTS`-bodied function was counted 90 times for 90 rows, and a
+plain-expression function was inlined and not counted. `track_functions = 'pl'` skips
+SQL-language functions; use `'all'`. See
+[function inlining](performance-patterns.md#function-inlining).
+
+### Text join and index conditions
+
+`Hash Cond`, `Merge Cond`, `Join Filter`, or a join's `Index Cond` comparing `text` or `varchar`
+columns (often shown with `::text` casts) means the key is compared under collation and stored in every
+referencing row and index. Join on ids and keep the string in a unique column; see
+[join on ids](../../postgres-schema-design/references/relations.md#join-on-ids-never-on-text).
+
+### Generic plans worse than custom plans
+
+A prepared statement can switch to a generic plan after several executions, planned without the
+parameter values. If a statement is fast in `psql` with literals but slow from the application,
+compare `EXPLAIN (GENERIC_PLAN)` for the statement with the plan for a real value. Estimates alone
+can hide the problem, and `GENERIC_PLAN` cannot be combined with `ANALYZE`; prepare the statement
+and compare `EXPLAIN (ANALYZE, BUFFERS) EXECUTE` for the same skewed value under
+`plan_cache_mode = force_generic_plan` and `force_custom_plan`. When the generic plan is much worse, fix the statistics or query shape first; set
+`plan_cache_mode = force_custom_plan` for that statement or role only with measured evidence.
+
+### Large sequential scans and bad estimates
+
+A `Seq Scan` over a large table that returns few rows and reads many buffers or removes many rows
+by filter is usually a missing or unusable index. A sequential scan on a small table, one that
+returns most rows, or one a parent `LIMIT` or `EXISTS` stops early (check the buffers) is fine. Compare `Plan Rows`
+with `Actual Rows` on every executed node (`Actual Loops` above zero; a never-executed node has no
+observed cardinality) that decides a join (scan inputs and join outputs): an estimate
+off by 10x or more can pick the wrong join type or order. Run `ANALYZE`, then consider a higher
+statistics target, or extended statistics for correlated columns within one table; extended
+statistics do not improve join selectivity, so for a join misestimate look at the join keys'
+statistics, the filters feeding the join, or the query shape before changing the query.
+
+## Checklist
+
+1. Total rows per node versus rows kept; `Rows Removed by ...`.
+2. Any SubPlan with loops equal to the outer rows.
+3. `Filter` that should be `Index Cond`; partition pruning (`Subplans Removed`).
+4. Function calls in `Filter` or output; count them with `pg_stat_xact_user_functions`.
+5. Text keys in join and index conditions.
+6. Generic versus custom plan for prepared statements.
+7. Estimate versus actual on join-deciding nodes.
+8. `Buffers` shared hit plus read totals against the rows returned; the split separates cache
+   pressure from reads that missed PostgreSQL's shared buffers; use OS or storage metrics
+   to judge physical I/O, since the OS cache may serve a shared read.

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

@@ -39,6 +39,24 @@ validation, then use URL FKs. Keep exact external protocol identifiers, capabili
 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.
 
+## Join on ids, never on text
+
+Keys are ids. A key compared as text runs under collation, and its string is copied into every
+referencing row and index. Keep the string as a unique column on the owning table and reference
+the row by id:
+
+```sql
+-- avoid: orders.account_code text REFERENCES accounts (code)
+CREATE TABLE accounts (id uuid PRIMARY KEY, code text NOT NULL UNIQUE);
+CREATE TABLE orders (id uuid PRIMARY KEY, account_id uuid NOT NULL REFERENCES accounts (id));
+```
+
+Resolve the string to an id once at the boundary, then join `orders.account_id = accounts.id`.
+Values matched as text by nature, such as free-form tags, are the exception; document them. Text
+in a join's `Hash Cond` or `Index Cond` is a plan red flag; the single lookup of the unique code
+at the boundary is expected and fine. See
+[reading plans](../../postgres-node-performance-tuning/references/reading-plans.md#text-join-and-index-conditions).
+
 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;

package/skills/retrospective-distill/SKILL.md

@@ -14,21 +14,25 @@ Use when completed retrospectives or journals should become durable follow-up wo
 
 1. Enumerate only completed, eligible session records with the `snapshot_export` tool of the
    `vouchington-tooling` MCP server, narrowing by `agent`, `version`, `parentSessionId`, exact
-   `data` fields, `dataArrayContains`, and `inactiveForHours`. It exports non-archived sessions to a
+   `data` fields, and `dataArrayContains`. It exports non-archived sessions to a
    private local file and returns the path, counts, checksum, and manifest, never the records.
    Before exporting, call `outbox_flush` and then `outbox_status` for every worktree that
    `git worktree list` reports, passing each path as `worktree`, and stop if any reports a
    `worktreePendingCount` above 0. Use the worktree count, never `pendingCount` or `status`, which
    cover only the caller's own session: the sessions to distill belong to other agents, and an
    archived session refuses later delivery, so a retained record would never be distilled. Outboxes
-   in removed worktrees or on other machines cannot be drained this way, so select with
-   `inactiveForHours` to give them time to deliver. Leave in-progress sessions intact. If a search
+   in removed worktrees or on other machines cannot be drained this way, so apply the age cutoffs under
+   [session shapes](#session-shapes-and-eligibility) to give them time to deliver. Leave in-progress sessions intact. If a search
    for `snapshot_export` (the tool names carry a harness prefix, see the
    [blackboard skill](../blackboard/SKILL.md)) finds no server, stop and report it; do not fall back
    to a CLI command.
 2. Before using any record, verify the file against the returned checksum, counts, and terminal
    manifest with the consumer's approved snapshot reader, and stop on a mismatch rather than
-   treating missing records as absent. Read full records, with their storage type, repository
+   treating missing records as absent. Require `manifest.schemaVersion` to be 1, `manifest.status`
+   to be `"complete"`, a nonempty `cleanupToken`, and manifest counts that exactly match the export
+   counts, including the terminal manifest record. Hand subagents only read-only partitions of the
+   verified file, never the original snapshot, and give each partition its own bounded session and
+   byte limits. Read full records, with their storage type, repository
    tags, source identity, coverage, and outcomes, from that file. Do not distill from
    `journal_entries`: it reads one session at a time and has no checksum or manifest to show that
    the read is complete. For repository-scoped work, filter sessions by
@@ -41,6 +45,8 @@ Use when completed retrospectives or journals should become durable follow-up wo
    by exact session/source identity and reject conflicting duplicate content. Records that differ
    only in their server-assigned `timestamp` are one event. Retain coverage,
    dropped counts, requested versus observed outcomes, and useful resolved findings.
+   Classify each session by [shape](#session-shapes-and-eligibility) and skip any that is not yet
+   eligible, with a reason.
 4. Cluster findings by root cause. Prefer a few broad actionable themes over many narrow issues.
    Treat a finding already linked to an open tracker as context, not a duplicate.
 5. Verify each candidate against the current base. Search existing issues and open changes before
@@ -63,6 +69,63 @@ Use when completed retrospectives or journals should become durable follow-up wo
    actionable dispositions with reasons. Keep the top five themes in human prose without dropping
    underlying findings or unresolved records.
 
+## Session shapes and eligibility
+
+Classify by each entry's `type`, never by rendered text. Deduplicate by session and `sourceEventId`
+first. Entries that differ only in the server-assigned `timestamp` are one event; any other
+difference is a conflicting payload and stays quarantined.
+
+| Shape                 | Definition                                                                                                                                                                                   |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Entry-type-unresolved | At least one entry has a missing type, a type other than `journal` or `retrospective`, or a feedback envelope that fails the shared validator, even if the session also has a retrospective. |
+| Retrospective         | Has a retrospective entry and no unresolved entry.                                                                                                                                           |
+| Checkpoint-only       | Has entries, no retrospective, and every entry is a historic hook-written checkpoint, identified by a structural checkpoint field.                                                           |
+| Journal-only          | Has entries, no retrospective, and at least one entry is not a checkpoint.                                                                                                                   |
+| Zero-entry child      | No entries and a non-null `parentSessionId`.                                                                                                                                                 |
+| Zero-entry root       | No entries and a null `parentSessionId`.                                                                                                                                                     |
+
+- The zero-entry split names session topology, not completion. A delegated child that died
+  mid-task looks identical to one that finished cleanly; never read it as "completed normally".
+- Report entry-type-unresolved sessions separately. Give them no issue-filing pass or archival this
+  run, whatever their age; do not treat an untyped entry as journal evidence.
+- Compute `retroAt` as the newest retrospective entry's `createdAt`, and `lastActive` as the newest
+  normalized entry's `createdAt`, falling back to the session's `createdAt` when it has no
+  entries. An identical replay does not advance activity; a new source event does.
+- Compute `retroCutoff = now - retroDays` and `sessionCutoff = now - sessionDays` once, from
+  caller-supplied non-negative finite day counts, and share both with every inspector so none reads
+  its own clock. Reject a negative or non-numeric count before exporting: it makes the cutoff
+  lie in the future or every comparison false, and these values gate archival.
+- Every shape except entry-type-unresolved is eligible when
+  `(has a retrospective AND retroAt < retroCutoff) OR (lastActive < sessionCutoff)`. Session age
+  alone makes a stale checkpoint-only, journal-only, or zero-entry session eligible, so a
+  retrospective-only gate cannot strand it. Everything else is not yet eligible; skip it with a
+  reason.
+- Export unfiltered rather than with `inactiveForHours`: a zero-entry session has no last entry and
+  never matches that filter, which would hide the feedback gaps this pass exists to sweep up.
+  Derive age from the cutoffs above; they supply the delay for outboxes in removed worktrees or on
+  other machines.
+- Journal-only and zero-entry evidence get full issue-filing rights, subject to the same duplicate,
+  current-state, and dependency checks as retrospective evidence, plus redaction: never quote a
+  journal entry's raw command string or stderr in an issue body, since a journal entry can carry
+  unredacted secrets.
+- Skip archival for sessions that contributed to a theme whose issue mutation failed this run, and
+  for sessions whose only themes were deferred, since deferral promises re-evaluation. Keep a theme
+  tied to a closed-without-merge issue or change eligible; do not treat open state alone as
+  conclusive. Preserve each theme's contributing session IDs through merging and deduplication.
+- Delegate partitions only to read-only inspectors, which must not call MCP, create issues, archive
+  sessions, edit files, or keep a copy of a partition. Have each return a compact disposition
+  summary: partition index, deduplicated themes with their session IDs, and each session's
+  disposition. Inspectors hand-read only journal-only and retrospective sessions; every other shape
+  is determined structurally.
+- Keep the verified snapshot until the last `session_archive`, because the archival check reads it.
+  Then remove the snapshot with the cleanup capability returned at export, and any partitions with
+  the separate receipt returned when they were created (the export capability cannot remove them),
+  in a cleanup path that runs even when no session is archived.
+- Report reviewed, fixed, duplicate, deferred, quarantined, actionable, created, updated,
+  not-yet-eligible, entry-type-unresolved, and archived counts with reasons, splitting eligible
+  sessions into retrospective and stale (checkpoint-only, journal-only, zero-entry child, and
+  zero-entry root).
+
 Use source records only for local verification and leave them in the repository's approved journal
 or retention system. Public issue bodies contain only the minimum bounded facts or redacted
 summaries needed to establish the problem, proposed work, relevant areas, and validation. Never

package/skills/revisit-followups/SKILL.md

@@ -26,5 +26,22 @@ issue policy, and review-record conventions first.
    duplicate repository or label authorization. Then clean up temporary collection artifacts and
    report skipped, covered, and created items.
 
+## Scope and collection
+
+- Accept a duration (`1w`, `2d`, `1m`) or ISO date. If absent, ask, proposing a one-week default,
+  then compute a date-only cutoff and fetch the base remote.
+- Treat comments on changes and issues as opt-in sources; bodies are the default.
+- Collect bodies first: for closed issues, unchecked boxes and partial numbered work lists are
+  candidates, and comments are fetched only for body candidates unless comments were requested. Do
+  not exclude a whole plan issue or rely on a fixed heading allowlist.
+- Search merged and closed work with `--limit 500`. A full page is truncation, not exhaustion: split
+  the date range at its midpoint, retaining both bounds for interior chunks; only the top-level
+  final chunk may be open-ended.
+- Keep splitting a full single day by timestamp (search dates accept ISO-8601 times); report
+  truncation only when the smallest timestamp bucket is still full.
+- Use an OS-temp scratch directory with separate candidate and verdict files; each delegated
+  collector gets its own file, and never append concurrently. Do not print fetched bodies outside
+  scratch files, and remove all scratch files after collection.
+
 Consumer wrapper owns: review journal format, default lookback, hosting provider, repository,
 issue taxonomy, and confirmation mechanism.

package/skills/stacked-prs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacked-prs
-description: Drain native GitHub stacks from the bottom ready layer; a ready lower layer does not freeze later work.
+description: Work native GitHub stacks bottom-up and merge the ready prefix in one command; a ready lower layer does not freeze later work.
 ---
 
 # Stacked pull requests
@@ -13,6 +13,13 @@ Use when a change is a chain of native GitHub stacked pull requests. Read local
 `AGENTS.md` first. They own whether this repository stacks, which tool creates, rebases, and merges
 a stack, and who may authorize a merge.
 
+- [gh-stack mechanics](references/gh-stack.md): commands, import, submit and verify, the forge as
+  the only truth.
+- [Drain and keep track](references/drain.md): ownership, shepherding, ready-prefix merge checks,
+  and reconciling the ledger.
+
+## Shape
+
 - Each pull request except the bottom one targets the pull request below it. The bottom pull
   request targets the default branch.
 - GitHub merges the selected pull request and every unmerged pull request below it, bottom-up, as
@@ -25,31 +32,55 @@ a stack, and who may authorize a merge.
   report. Local stack metadata is stale after a rebase, relink, or manual recovery.
 - The bottom layer's base must be the default branch. Otherwise merge that base or re-root the
   stack onto the default branch before draining.
-- Merge the bottom-most ready layer as soon as it is ready. Do not wait for layers above it.
-  Nothing in the stack merges on its own.
-- Name that bottom-most unmerged layer as the merge target. Naming a higher layer merges more than
-  this step when everything below is also ready, and is unavailable when it is not.
+
+## Work bottom-up
+
+- Work bottom-up. Write layers in stack order, and never start a layer before the one below it is
+  in decent shape.
+- A lower layer is in decent shape when it is committed, its local checks have passed, its pull
+  request is open with an updated body, and shepherding has started. Decent shape does not mean
+  green CI, ready for review, or merged.
+- Start the next dependent layer once the lower layer is in decent shape. Do not wait for merge,
+  a ready-delay, or green CI.
+- On each shepherd result, act on the lowest owned layer that is not ready before any higher
+  layer. Put each fix on the lowest layer that owns it. A bottom layer that reaches ready early
+  frees the ready prefix above it to merge in one command.
+- Before a command that adds layers to a stack, such as `gh stack add` or `gh stack link`, add the
+  forge's open-layer count, plus every locally tracked layer not yet submitted, to every layer the
+  command would add. `gh stack add` creates only a local branch, so repeated adds before a submit
+  are invisible to the forge count. Above the layer cap (default 10),
+  open independent work as its own pull request on the default branch and hold dependent work
+  until the bottom layers merge.
+- A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
+  layer. Keep readying every other owned layer.
+
+## Merge the ready prefix
+
+- Do not merge one layer at a time, and do not wait for the whole stack. Layers accumulate rebase
+  surface, CI cost, and review context, and drift against the default branch.
+- The ready prefix is the bottom-most open layer plus every consecutive layer above it that is
+  also ready and inside the human's approval. As soon as the bottom layer is ready, merge the ready
+  prefix with one command whose target is the prefix's top layer. When every layer is ready and
+  approved, the target is the top of the stack.
+- Nothing in the stack merges on its own. Run the merge checks in
+  [Drain and keep track](references/drain.md#merge-the-ready-prefix) before each merge.
 - After a merge, GitHub retargets the next unmerged layer onto the default branch. That layer is
   the new bottom.
-- On a stall, or when a layer closes without merging, stop if the bottom layer is otherwise ready.
-  Report every layer and ask before merging that bottom layer.
+- On a stall, or when a layer closes without merging, stop if the bottom layers are otherwise
+  ready. Report every layer and ask before merging that ready prefix.
 - A stall blocks only layers that depend on it. Ready the others. Pause the whole drain only when
   nothing further can be readied without the blocked layer.
+
+## Ownership and workers
+
 - Act only on layers assigned to you. Report the other layers; do not change them.
 - One worker per native stack implements that stack and runs its shepherd poll. The parent does
   not poll. It reconciles stacks, starts a worker, and carries merge questions to the human.
 - Start shepherding when the first owned pull request exists.
-- A lower layer is in decent shape when it is committed, its local checks have passed, its pull
-  request is open with an updated body, and shepherding has started. Decent shape does not mean
-  green CI, ready for review, or merged.
-- Start the next dependent layer once the lower layer is in decent shape. Do not wait for merge,
-  a ready-delay, or green CI.
-- A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
-  layer. Keep readying every other owned layer.
 - Independent stacks run at the same time, one worker each. Dependent unmerged work is another
   layer of the same stack, not a second stack whose base is an unmerged head.
 - At most one poll process per stack. The parent does not run a second poll for the same stack.
 - This skill does not grant a merge. Merge authorization stays with the consumer.
 
-Consumer wrapper owns: default branch, stacking tool and commands, merge-selector syntax, and
-merge authorization.
+Consumer wrapper owns: default branch, stacking tool and commands, merge-selector syntax, layer cap,
+pull request description tool, ownership stamp format, and merge authorization.