vouchington-tooling 0.42.0 → 0.44.0

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/pr-description/SKILL.md

@@ -54,6 +54,14 @@ not evidence of a miss; classify genuine CI-only or external infrastructure fail
 Retain confirmed gap records after CI turns green. Diagnose the failure through the repository's
 CI investigation workflow; a failed status alone does not establish a gap.
 
+Create, update, and validate pull requests through the `pr_create`, `pr_update`, and `pr_validate`
+MCP tools with structured input, not by hand-writing a body: pass `title`, `summary`, `impact`,
+`relatedIssues` (`closes` or `refs`, each with a reason), `details` (Markdown paragraphs or
+bullets), `base`, `agent`, optional `model`, `mode`, and `workspaceSetup`. The server renders the
+required headings and provenance lines, runs the repository's policy validation, and blocks on its
+errors, so put the guidance above into `summary`, `impact`, and `details`. Run `pr_validate` first
+to preview the rendered body. `pr_update` preserves the live Shepherd Journal.
+
 Use the repository's approved PR tooling and preserve sections managed by its review automation
 verbatim. Close only issues fully resolved and explain non-closing issue links. Apply this guidance
 to descriptions being created or updated, not a bulk rewrite of historical pull requests.

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.

package/skills/stacked-prs/references/drain.md

@@ -0,0 +1,168 @@
+# Drain and keep track
+
+Shepherding a layer to ready and merging are different acts. The first covers every pull request
+the worker owns in the stack at once. The second lands the ready prefix in one command, and it is
+never the agent's own decision.
+
+## Establish scope
+
+1. Resolve the stack from `pulls/<any-layer>.stack`, and record whether the field was present. A
+   stack object supplies its number; an explicit `null` means no registered stack. A missing
+   preview field: query `stacks?pull_request=<N>`, where one result is the stack and zero means
+   unstacked. Do not treat an empty `.stack.number` alone as proof
+   that a pull request is unstacked.
+2. Read topology from `repos/{owner}/{repo}/stacks/<n>`, ordered bottom to top. A
+   `closed && merged_at == null` layer below an open one means the stack is broken. Report it to
+   the human, and never merge across it.
+3. Partition by ownership, using that topology read plus each member's body from `pulls/<N>` (the
+   stack response has no bodies). Shepherd only owned pull requests. Never
+   poll, fix, rebase, or push the others, but list them in every report. Owned means this session
+   opened the pull request, or a human named it in this session.
+   - The opened-by-me half is a durable remote fact when the repository's pull request description
+     tool stamps each body with the authoring harness and session id. Compare the stamp with the
+     current session id.
+   - The named-by-a-human half is conversational and cannot be recovered remotely. That is
+     acceptable, because the human can restate it after a compaction.
+   - Degrade explicitly. A body without a matching stamp, or with a stamp naming no session id,
+     is not owned. Report it as "ownership unverifiable" and never poll it.
+   - A parent may assign its stack to one worker by listing the pull request numbers and the
+     session id stamped on them. The worker treats that list as assigned and still refuses any
+     layer outside it.
+
+## Shepherd the owned layers
+
+Run one stack shepherd poll for the assigned stack, and follow its printed instructions.
+
+- A shepherd's own "owned" mark can mean only that the author login equals the authenticated
+  viewer. Several sessions often share one account, so filter every printed row against the
+  ownership partition above before acting. Never start a per-pull-request session, fix, or push
+  for a row outside it, even when the shepherd marks it owned.
+- Apply code fixes, rebases, pushes, and review mutations to owned layers only. Report work
+  surfaced on an unowned layer to the human.
+- Fix on the owning layer. Commit there, rebase the layers above it (`gh stack rebase --upstack`),
+  `gh stack sync` when there are no local stack commits, `gh stack push` once, then rerun the
+  shepherd.
+  `rebase --upstack` and `push` act through the top of the stack. When an unowned layer sits above
+  an owned one, stop at that layer: do not rebase or push it, and hand the remaining rebase and
+  push to its owner.
+- Start the shepherd with the first pull request. While the poll is in a pure wait and the
+  worktree is clean, commit the next layer once the lower layer is in decent shape. On a
+  fix-code result, finish it on the owning layer before more upper edits. A ready-delay schedules
+  the rerun: continue owned work on a later layer, and do not invent unrelated work.
+- Never run a printed merge command unless the human's approval covers that layer and every open
+  layer below it, and the checks below pass. `gh stack merge <pr>` lands that pull request and
+  every layer below it.
+- Mutating git does not parallelize. Stop the poll before a rebase, sync, or push in the stack's
+  shared worktree, because other layers' branches can be rewritten underneath it. Discard a poll
+  result that was in flight across the mutation, and start the poll again after the push lands.
+  Run at most one git mutation at a time.
+
+### Upper-only fast-forward
+
+A queued lower layer, or any lower layer that must not be rewritten, does not stop an upper-only
+fast-forward, or upper review and CI work that does not write git.
+
+- Before that push, read the forge and capture the parent head, the parent base, the upper remote
+  head, and the stack order. Read all four again immediately before pushing.
+- Push only when all four still match, the local upper commit fast-forwards that remote head, and
+  it still contains the parent. If anything differs, or the lower layer merges or leaves the queue
+  meanwhile, stop and read the forge again. Never push from a stale capture.
+- Do not amend, force-push, `gh stack sync`, or `gh stack rebase` a queued parent: each rewrites
+  it. When the lower layer changes, re-read topology before branch work that depends on the new
+  parent.
+
+### Escalations persist to the pull request
+
+When a layer needs a human, because it is ready and waiting on a merge decision or genuinely
+blocked:
+
+- Apply the repository's needs-human label and post one comment per escalation event, not per
+  poll, with the layer's position and what it needs.
+- When a layer re-escalates, minimize the superseded comment (GraphQL `minimizeComment`,
+  `classifier: OUTDATED`). Clear the label once the layer no longer needs a human.
+- A relayed merge command is for visibility only. The shepherd picks its target from ready
+  results alone and does not know what the human approved.
+
+## Report
+
+When the owned set settles, present the stack bottom to top: each layer's number, owner, state,
+and whether it is ready or blocked and why. Never leave a ready bottom layer under a blocked upper
+layer without saying so.
+
+## Merge the ready prefix
+
+The ready prefix is the bottom-most open layer plus every consecutive layer above it that is also
+ready and inside the approval. Its top layer is the merge target. A shepherd that prints a merge
+of its highest ready layer may name a layer above the approved range. Target the highest approved
+layer of the prefix instead; that is still one command.
+
+Merge only on explicit human approval. The approval names what it covers: one layer, a range, or
+the whole stack. Approving the whole stack also covers the next ready prefix after an earlier
+merge. It does not cover a layer added after the approval. Ask before merging any layer outside
+it.
+
+Immediately before each approved merge, run these checks in order:
+
+1. `gh api repos/{owner}/{repo}/stacks/<target>` must return 404. `gh stack merge` resolves a bare
+   number as a stack number first, then a pull request number. A 200 response means `--yes` would
+   merge every layer of that stack. Stop and ask.
+2. Re-read topology. Confirm every layer from the bottom-most open layer up to the target is open,
+   ready, and inside the approval, with nothing broken below.
+3. For every layer in the prefix, capture `pulls/<N>.head.sha` before the final poll and after it.
+   They must match. A mismatch means a push landed inside the evaluation window: discard the
+   verdict and poll again.
+4. `gh stack merge <target> --yes` with the repository's merge strategy. It lands the target and
+   every open layer below it, which is the ready prefix.
+5. Do not `gh stack sync` here. Return to step 2 of [Establish scope](#establish-scope) and
+   re-read topology remotely: rebasing right after a merge can replay already-landed commits from
+   a stale local base ref. Keep shepherding the layers above. When the new bottom is ready, merge
+   the next ready prefix the same way. Before any local edit, rebase, or push on a remaining
+   layer, rerun the fetch and ahead/behind check in
+   [Import a stack](gh-stack.md#import-a-stack-before-acting-on-it): GitHub rebases the next
+   layer remotely, so local upper branches are stale until fast-forwarded. The drain is complete when no unmerged owned layer remains.
+
+The window between the last head read and the merge cannot be closed, because `gh stack merge`
+has no head-SHA pin. Branch protection and rulesets are evaluated when the merge runs, and stacks
+cannot bypass merge requirements. If the merge is rejected, re-read topology instead of retrying
+blindly. Under a merge queue, a successful `gh stack merge` only enqueues: the prefix queues
+together, and a failing layer is ejected along with the layers above it. The next topology
+re-read handles that.
+
+When you stop or are blocked (an unresolved escalation, an interrupt or pause, repeated fixes with
+no progress, or an external blocker), report each layer's number and state. If the bottom layers
+are ready, ask whether to merge that ready prefix before continuing.
+
+## Keep track: derive the ledger
+
+A hand-kept list of "pull requests I opened" drifts, and a compaction or new session erases it.
+The ownership stamp makes the ledger derivable, so state is re-read instead of recalled.
+
+Reconcile broadly, partition narrowly. A new session opens a rival stack because it never looks for
+the old one, so the reconcile query is deliberately unfiltered; only the partition is
+session-filtered:
+
+```bash
+# Reconcile, unfiltered: it finds stacks this session did not create.
+gh api --paginate repos/{owner}/{repo}/stacks --jq '.[] | select(.open)'   # 30 per page
+gh api --paginate "repos/{owner}/{repo}/pulls?state=open&per_page=100" \
+  --jq '.[] | {number, title, user: .user.login, body}'
+# Partition: apply the ownership check from Establish scope to that output.
+```
+
+- Reconcile before starting anything new. At the start of work, and before opening any pull
+  request or stack, surface every open stack or unfinished layer, whoever made it.
+- Close out; do not drift away. Close a layer that will not land. Ending or pausing a session with
+  owned open layers requires reporting them.
+- Continue the stack instead of starting a parallel one. Dependent work for an owned open stack is
+  a new layer (`gh stack add`, after the layer cap check). For an unowned open stack, report it and
+  ask instead of adding to it or starting a rival.
+- Derive state (which pull requests and stacks exist, their positions, their status) every time;
+  never cache it. Only intent, such as which stack is being built or what a planned layer is for,
+  belongs in the session's plan or journal, and it is a plan, not a record.
+
+Known gaps:
+
+- An ownership stamp is a body line any writer can edit. It is a signal, not an authorization
+  boundary, and that is sound only because every merge is human-gated.
+- Stack and pull request numbers share no guaranteed disjointness, which is why merge check 1
+  runs before every merge.