<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/pr-landing/">
  <id>https://docs.spec-kitty.ai/development/how-to/pr-landing/</id>
  <title>Landing Contributor PRs: The Maintainer Runbook</title>
  <updated>2026-11-12T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/pr-landing/"/>
  <summary>The maintainer workflow for landing contributor PRs: claim, worktree isolation, rebase, red classification, folds, red-first checks, push, hand-off and post-merge cleanup.</summary>
  <content type="html">&lt;span id=&quot;landing-contributor-prs-the-maintainer-runbook&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Audience&lt;/strong&gt;: Maintainers taking contributor PRs from “open with red CI” to
“merge-ready, evidence posted, operator merges”.
&lt;strong&gt;Issue&lt;/strong&gt;: &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2341&quot;&gt;#2341&lt;/a&gt;
&lt;strong&gt;Origin&lt;/strong&gt;: The 2026-07-04 landing pass (#2332, #2336, #2338, #2239, #2238),
where this workflow was run end-to-end and its friction points were logged.&lt;/p&gt;
&lt;p&gt;The deliverable of a landing pass is never a merge. It is a PR that is green,
carries a full evidence trail in its comment thread, and states
any landing-order constraints — so the operator can merge it without
re-deriving the adjudication. The maintainer never merges
(see &lt;a href=&quot;#11-hand-off--the-operator-merges&quot;&gt;step 11&lt;/a&gt;).&lt;/p&gt;
&lt;h2 id=&quot;the-workflow-at-a-glance&quot;&gt;The workflow at a glance&lt;/h2&gt;
&lt;p&gt;Before step 1, &lt;a href=&quot;#before-you-claim-check-the-pr-is-handed-off-and-worth-landing&quot;&gt;check the PR is handed off and worth landing&lt;/a&gt;.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;a href=&quot;#1-claim-before-touching&quot;&gt;Claim before touching&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#2-one-isolated-worktree-per-pr&quot;&gt;One isolated worktree per PR&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#3-rebase-onto-current-upstreammain-first&quot;&gt;Rebase onto current upstream/main first&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#4-classify-every-red-check&quot;&gt;Classify every red check&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;Folds: remediation commits on the contributor branch&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#6-red-first-verification-for-bugfix-prs&quot;&gt;Red-first verification for bugfix PRs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#7-review-focus-areas-beyond-ci&quot;&gt;Review focus areas beyond CI&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#8-adversarial-squad-for-architectural-or-api-surface-prs&quot;&gt;Adversarial squad for architectural or API-surface PRs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#9-push-discipline&quot;&gt;Push discipline&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#10-post-the-remediation-summary&quot;&gt;Post the remediation summary&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#11-hand-off--the-operator-merges&quot;&gt;Hand-off — the operator merges&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#12-after-the-merge-remove-the-landing-worktree&quot;&gt;After the merge: remove the landing worktree&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;#13-follow-up-hygiene&quot;&gt;Follow-up hygiene&lt;/a&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;before-you-claim-check-the-pr-is-handed-off-and-worth-landing&quot;&gt;Before you claim: check the PR is handed off and worth landing&lt;/h2&gt;
&lt;p&gt;Start with two read-only checks.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Is it handed off?&lt;/strong&gt; A new PR is opened as a draft, followed, fixed to green, and
then flipped to “ready for review”. The flip is the hand-off to the maintainers: it
signals that a landing pass is safe to start. A draft PR is not handed off. Run
&lt;code dir=&quot;auto&quot;&gt;gh pr view &amp;#x3C;N&gt; --repo spec-kitty/spec-kitty --json isDraft,author,statusCheckRollup&lt;/code&gt;;
if &lt;code dir=&quot;auto&quot;&gt;isDraft&lt;/code&gt; is true, stop before you touch the branch. The first thing in your reply
to the operator is a prominent warning that the PR is STILL A DRAFT AND NOT HANDED
OFF FOR LANDING, with its author and CI state, and the question whether to land it
anyway. Rebase, push or comment only after an explicit go-ahead.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Is it worth landing?&lt;/strong&gt; Size the PR on two axes: old (its base is far behind
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, an aging contributor branch) and substantive (a capability, a fix or a
contract change, as opposed to a version bump, a dependency pin, a regenerated file
or a typo). When unsure, treat it as old and substantive.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Old or substantive: run the full check.&lt;/strong&gt; Was the change already landed by
another PR or Mission (search the changelog, &lt;code dir=&quot;auto&quot;&gt;git log -S&lt;/code&gt; and the referenced
issues)? Does its approach still fit the current design, or did a seam it depends
on move? Does the problem still reproduce on current &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;? Post the result as a
PR comment, with evidence: &lt;strong&gt;LAND&lt;/strong&gt; as is, &lt;strong&gt;RESCOPE&lt;/strong&gt; (keep the durable part) or
&lt;strong&gt;CLOSE&lt;/strong&gt; (superseded or moot). Continue only on LAND; otherwise report the
recommendation to the operator and wait for the answer.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Recent and mechanical: run the short check.&lt;/strong&gt; Is the change accurate (correct and
coherent), desirable (actually wanted) and aligned with current conventions? If so,
record the LAND call in your first comment and continue.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;What you update at the end depends on the outcome. A RESCOPE gets a changelog entry
for the kept part only; a CLOSE gets a closing rationale in the PR body instead of a
changelog entry.&lt;/p&gt;
&lt;h3 id=&quot;prs-prepared-by-the-skykitty-fleet&quot;&gt;PRs prepared by the SkyKitty fleet&lt;/h3&gt;
&lt;p&gt;A &lt;code dir=&quot;auto&quot;&gt;squad:passed&lt;/code&gt; label (see &lt;a href=&quot;/development/agent-fleet/&quot;&gt;the agent fleet&lt;/a&gt;; the fleet is now
switched off and the label was deleted, so this applies to PRs it prepared earlier) meant the fleet’s
review passed against the base the PR had at that time. It does not mean the PR is
ready now. After the rebase:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Do not regenerate the generated docs surfaces.&lt;/strong&gt; The docs retrieval index
(&lt;code dir=&quot;auto&quot;&gt;docs/development/docs-retrieval-index.yaml&lt;/code&gt;), the page inventory
(&lt;code dir=&quot;auto&quot;&gt;docs/development/page-inventory.yaml&lt;/code&gt;) and the ADR era table rows are
regenerated on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; after merge by the &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt; bot pull request
(&lt;code dir=&quot;auto&quot;&gt;docs-index-regen.yml&lt;/code&gt;). A PR that edits them fails the &lt;code dir=&quot;auto&quot;&gt;docs-lint&lt;/code&gt; guard
(&lt;code dir=&quot;auto&quot;&gt;scripts/ci/check_generated_docs_untouched.py&lt;/code&gt;); revert such an edit with
&lt;code dir=&quot;auto&quot;&gt;git checkout origin/main -- &amp;#x3C;path&gt;&lt;/code&gt;. Their staleness findings in
&lt;code dir=&quot;auto&quot;&gt;check_docs_freshness --ci&lt;/code&gt; are warnings, and &lt;code dir=&quot;auto&quot;&gt;spec-kitty docs query&lt;/code&gt; on a branch
lags by the pages that have not merged yet. The &lt;code dir=&quot;auto&quot;&gt;ci/regen-docs-index&lt;/code&gt; branch is
bot-owned and rebuilt from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; on every docs merge: approve and merge its PR
promptly, and never push to that branch by hand (the next run force-pushes over
any manual commit).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fix the fleet’s follow-up issues.&lt;/strong&gt; The fleet files its smaller findings as
separate issues that reference the PR. Search for them
(&lt;code dir=&quot;auto&quot;&gt;gh issue list --repo spec-kitty/spec-kitty --search &quot;#&amp;#x3C;N&gt;&quot;&lt;/code&gt;, plus the PR’s own
comments), fix each one in this landing (or at least make the PR-body correction it
asks for), and add &lt;code dir=&quot;auto&quot;&gt;Closes #&amp;#x3C;n&gt;&lt;/code&gt; to the PR body next to the PR’s own issue line.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;1-claim-before-touching&quot;&gt;1. Claim before touching&lt;/h2&gt;
&lt;p&gt;Post a claim comment on the PR &lt;strong&gt;before&lt;/strong&gt; any rebase or review work: what you
are picking up, in which landing queue, and what you plan to do. One claim per
PR in the pass, posted first.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;unset&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;GITHUB_TOKEN&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# keyring auth has full repo scope; a limited env token may not&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pr&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;comment&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;N&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--repo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty/spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--body&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;Claiming this PR for today&apos;s landing pass: rebase onto upstream/main, adjudicate red checks, fold fixes as needed. Evidence to follow.&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Why: it prevents duplicated maintainer effort when several PRs are being
landed in parallel, and it means the contributor is never surprised by
maintainer commits appearing on their branch.&lt;/p&gt;
&lt;h2 id=&quot;2-one-isolated-worktree-per-pr&quot;&gt;2. One isolated worktree per PR&lt;/h2&gt;
&lt;p&gt;Never touch the primary checkout — a mission session may own it. Give every
PR its own worktree:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;fetch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pull/&amp;#x3C;N&gt;/head:pr-&amp;#x3C;N&gt;-local&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/pr-&amp;#x3C;N&gt;-landing&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pr-&amp;#x3C;N&gt;-local&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/pr-&amp;#x3C;N&gt;-landing&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Each worktree builds its own &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt; virtualenv on the first &lt;code dir=&quot;auto&quot;&gt;uv run&lt;/code&gt; — expect
roughly 40 seconds and some disk on that first command. That is normal, not a
hang.&lt;/p&gt;
&lt;h2 id=&quot;3-rebase-onto-current-upstreammain-first&quot;&gt;3. Rebase onto current upstream/main first&lt;/h2&gt;
&lt;p&gt;Contributor branches are routinely 100+ commits behind. Every adjudication —
tests, gates, review — happens on the rebased tip, not the stale base:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;fetch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;main&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;rebase&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;A PR adds its changelog entry as a fragment in &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;id&gt;.&amp;#x3C;section&gt;.md&lt;/code&gt;, see &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/changelog/unreleased/README.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/README.md&lt;/code&gt;&lt;/a&gt;),
so the changelog no longer conflicts on rebase. If an older PR still edits
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt; and conflicts there, move its entry into a fragment
instead of resolving the conflict by keeping both sides; keeping both sides is how
duplicate entries and a second &lt;code dir=&quot;auto&quot;&gt;updated:&lt;/code&gt; key landed before.&lt;/p&gt;
&lt;h2 id=&quot;4-classify-every-red-check&quot;&gt;4. Classify every red check&lt;/h2&gt;
&lt;p&gt;This is the core reviewer decision point. Diagnose each red check on the
rebased tip and classify it into exactly one of four bins:&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Classification&lt;/th&gt;&lt;th&gt;What it looks like&lt;/th&gt;&lt;th&gt;Action&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;PR defect&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The PR’s own change breaks a test or gate&lt;/td&gt;&lt;td&gt;Fix it on the branch (a “fold”, &lt;a href=&quot;#5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;step 5&lt;/a&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Contract the PR legitimately crosses&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A seam move-set completeness gate, a census tolerance band&lt;/td&gt;&lt;td&gt;Re-pin the contract &lt;strong&gt;in the same PR&lt;/strong&gt;, with a dated rationale in the pin&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Pre-existing main breakage&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The same red reproduces on an unrelated main-based branch&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Fold the fix in by default&lt;/strong&gt; (&lt;a href=&quot;#5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;step 5&lt;/a&gt;) — keep main green even for a red the PR did not cause — &lt;em&gt;unless&lt;/em&gt; one of the two carve-outs below applies&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Perf-budget flake&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A budget gate trips without a correctness signal&lt;/td&gt;&lt;td&gt;Note it, watch for recurrence, tune the budget at the root if it repeats — never retry-to-green&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Start with main’s own CI run at the merge-base — it is cheaper and more
decisive than any local rerun.&lt;/strong&gt; CI already ran the same shards against the
commit your branch is based on, so the comparison is a fetch, not a test run:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;unset&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;GITHUB_TOKEN&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;list&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--repo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty/spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--branch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;main&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--limit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;5&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--json&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;databaseId,name,conclusion,headSha&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# then, per failing job, pull the logs and diff the failing-test sets:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;gh&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;api&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--allow-escape-sequences&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;/repos/spec-kitty/spec-kitty/actions/jobs/&amp;#x3C;job-id&gt;/logs&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;sed&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;s/\x1b\[[0-9;]*m//g&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-E&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;^FAILED|short test summary| failed,&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Two things make this decisive rather than merely suggestive:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Match on test id &lt;em&gt;and&lt;/em&gt; assertion text&lt;/strong&gt;, not just job status. A job can be
red on both sides for different reasons.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Compare the pass counts too.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;1 failed, 572 passed&lt;/code&gt; on main against
&lt;code dir=&quot;auto&quot;&gt;1 failed, 583 passed&lt;/code&gt; on the PR proves the PR added 11 tests and no
failures. That single line refutes “the PR broke something” faster than any
argument.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Decompose composite jobs.&lt;/strong&gt; A composite job is not one check. The former
&lt;code dir=&quot;auto&quot;&gt;lint&lt;/code&gt; job ran schema generation, &lt;code dir=&quot;auto&quot;&gt;ruff&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;commitlint&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;markdownlint&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pip-audit&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;bandit&lt;/code&gt; as separate steps (the security
scans now run only in the nightly &lt;code dir=&quot;auto&quot;&gt;security-scans&lt;/code&gt; job). Never classify a
composite job as a unit: extract the failing &lt;strong&gt;steps&lt;/strong&gt; on both sides and
compare those. On the 2026-08-04 pass,
&lt;code dir=&quot;auto&quot;&gt;pip-audit&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;bandit&lt;/code&gt; were red on main (pre-existing) while &lt;code dir=&quot;auto&quot;&gt;commitlint&lt;/code&gt;
and &lt;code dir=&quot;auto&quot;&gt;markdownlint&lt;/code&gt; were introduced by the folds — a distinction invisible at
job level:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-nE&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;##\[group\]Run |##\[error\]Process completed&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;log&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;awk&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;/error/{print prev} {prev=$0}&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Then reproduce locally only for the reds you still need to settle:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/repro-main&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/repro-main&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;PWHEADLESS&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;failing&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;test&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-q&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;A red there too confirms the failure is pre-existing, not the PR’s. &lt;strong&gt;The
default is then to fold the fix in anyway&lt;/strong&gt; (boy-scout / campsite-clean,
&lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_025&lt;/code&gt;) — a stale generated artifact, a forgotten regen, or a small
unwired reference are all fixable inline, and a landing pass that leaves an
easy pre-existing red on the board just defers the cost and keeps main red for
longer. Two carve-outs override that default:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A &lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt;-marked red-first test.&lt;/strong&gt; An intentionally-failing,
issue-pinned reproduction of an open P0 bug (per
&lt;a href=&quot;/adr/3.x/2026-07-17-1-red-main-is-honest-ci-is-release-authority/&quot;&gt;ADR 2026-07-17-1&lt;/a&gt;,
Amendment 2026-10-04) carries &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro(issue=N)&lt;/code&gt;. It is a
&lt;em&gt;deliberate&lt;/em&gt; red signal that holds the nightly, and so the release, open until
the P0 is fixed — &lt;strong&gt;leave it red.&lt;/strong&gt; Do not fold it to green; the product fix
that closes its tracking issue is separate, dedicated work, never a
landing-pass fold. Greening it here would erase the honest release-blocker
signal the ADR exists to preserve.&lt;/p&gt;
&lt;p&gt;A pull request never runs these tests: &lt;code dir=&quot;auto&quot;&gt;tests/_support/p0_repro.py&lt;/code&gt; deselects
them unless &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_P0_REPRO=1&lt;/code&gt; is set, and only the nightly
&lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; job sets it. So a landing pass meets one only in a nightly run or
an explicit opt-in run (&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_P0_REPRO=1 uv run --frozen pytest -m p0_repro -q&lt;/code&gt;).
Each failure starts with an &lt;code dir=&quot;auto&quot;&gt;[OPEN P0 #N]&lt;/code&gt; banner naming the issue. Details:
&lt;a href=&quot;/development/reference/red-main-and-release-readiness/#where-the-reproduction-runs-the-nightly-p0-repro-lane&quot;&gt;Red Main and Release Readiness&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;regression&lt;/code&gt; marker is a different thing: it pins a bug that is already
&lt;strong&gt;fixed&lt;/strong&gt;, and it runs per PR. A red &lt;code dir=&quot;auto&quot;&gt;regression&lt;/code&gt; test is a real failure in
the PR, not a deliberate signal. Fold it or fix the code.&lt;/p&gt;
&lt;p&gt;Check for the marker per test, not per file. It is applied as a decorator on
the individual test while the module’s &lt;code dir=&quot;auto&quot;&gt;pytestmark&lt;/code&gt; may list only category
markers, so a file-level grep reports “unmarked” for a properly pinned
reproduction:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;grep&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-n&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;pytest.mark.p0_repro&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# catches both forms&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A fix that is mission scope and cannot reasonably be folded.&lt;/strong&gt; If the real
fix belongs to a distinct mission — wide blast radius, its own spec/design, an
in-flight mission’s own reconciliation — do not cram it into the contributor
PR. Instead &lt;strong&gt;accept the failure as an honest P0 red&lt;/strong&gt;: file or find the P0
issue, pin the failing test to it with &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro(issue=N)&lt;/code&gt;, and
leave it red per
&lt;a href=&quot;/development/reference/red-main-and-release-readiness/&quot;&gt;Red Main and Release Readiness&lt;/a&gt;.
The marker takes the test out of per-PR CI and into the nightly &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt;
lane, so the PR still lands green. Do not mark it &lt;code dir=&quot;auto&quot;&gt;regression&lt;/code&gt;, which would
keep it red in every PR. Never retry-to-green.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;See &lt;a href=&quot;/development/how-to/manage-issue-tracker/#triaging-issues-type-severity-and-release-blocking-bugs&quot;&gt;manage-issue-tracker.md&lt;/a&gt;
for the type/severity triage this leans on, and
&lt;a href=&quot;/development/testing/testing-flakiness/&quot;&gt;testing-flakiness.md&lt;/a&gt; for the never-retry-to-green rule
behind the fourth bin.&lt;/p&gt;
&lt;h3 id=&quot;multi-wp-lanes-classify-against-the-true-base-not-the-lane-tip&quot;&gt;Multi-WP lanes: classify against the true base, not the lane tip&lt;/h3&gt;
&lt;p&gt;A mission with dependency-merged lanes (&lt;code dir=&quot;auto&quot;&gt;lanes.json&lt;/code&gt;, &lt;a href=&quot;/architecture/execution-lanes/&quot;&gt;execution-lanes.md&lt;/a&gt;)
gives a downstream WP’s lane tip a branch that already &lt;strong&gt;contains every
upstream WP it depends on&lt;/strong&gt; — the tip is not close to the mission’s own base,
it is ahead of it by however many WPs merged in first. Diffing or classifying
reds against that lane tip mixes in work this PR did not write.&lt;/p&gt;
&lt;p&gt;Always classify against the &lt;strong&gt;true base&lt;/strong&gt;, computed fresh, not against the
lane tip and not against a remembered branch point:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;merge-base&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;mission-branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Reds that reproduce between that merge-base and the lane tip are &lt;strong&gt;pre-existing
or upstream-WP fallout&lt;/strong&gt;, not this WP’s defect — apply the same four-bin
classification above, but with the merge-base as the comparison point.&lt;/p&gt;
&lt;p&gt;One concrete trap this produces: a &lt;code dir=&quot;auto&quot;&gt;mock.patch.object(...)&lt;/code&gt; raising
&lt;code dir=&quot;auto&quot;&gt;AttributeError&lt;/code&gt; inside a red you have classified as “pre-existing” is very
often &lt;strong&gt;migration fallout&lt;/strong&gt; — an earlier WP in the same dependency chain
renamed or removed the attribute the mock patches — not a defect in the WP
under review. Confirm by checking whether the patched attribute still exists
on the target at the merge-base; if it does not, the fix belongs to whichever
WP renamed it, not to a fold on this PR.&lt;/p&gt;
&lt;h3 id=&quot;stale-stack-diagnostic-two-dot-vs-three-dot-diff&quot;&gt;Stale-stack diagnostic: two-dot vs three-dot diff&lt;/h3&gt;
&lt;p&gt;A “small fix” PR whose diff shows charter, doctrine, or other governance
files it has no business touching is a symptom of a &lt;strong&gt;stale stack&lt;/strong&gt;: the
branch was cut before a since-merged doctrine change, and rebasing (or a
naive two-dot diff) is smuggling that governance change back in as if it
were part of this PR.&lt;/p&gt;
&lt;p&gt;Tell the two apart with git’s own diff-base semantics:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;diff&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main..HEAD&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# two-dot: literal tip-to-tip diff&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;diff&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main...HEAD&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# three-dot: diff since the merge-base&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Two-dot&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;..&lt;/code&gt;) diffs the two commits directly — if &lt;code dir=&quot;auto&quot;&gt;upstream/main&lt;/code&gt; has
moved on, this includes both “what the PR changed” &lt;em&gt;and&lt;/em&gt; “what upstream/main
changed since,” conflated into one diff.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Three-dot&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;...&lt;/code&gt;) diffs from &lt;code dir=&quot;auto&quot;&gt;git merge-base upstream/main HEAD&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; — only the PR branch’s own commits, regardless of how far
&lt;code dir=&quot;auto&quot;&gt;upstream/main&lt;/code&gt; has since moved.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If the three-dot diff is clean (only the PR’s intended files) but the two-dot
diff shows charter/governance files, the branch is stale, not defective: fetch
and rebase onto current &lt;code dir=&quot;auto&quot;&gt;upstream/main&lt;/code&gt; (&lt;a href=&quot;#3-rebase-onto-current-upstreammain-first&quot;&gt;step 3&lt;/a&gt;)
before re-classifying. If charter/governance files still show up in the
&lt;strong&gt;three-dot&lt;/strong&gt; diff, that is a real defect — the PR is genuinely carrying
governance changes it should not — and belongs in the “PR defect” bin, not the
“stale stack” bin.&lt;/p&gt;
&lt;h2 id=&quot;5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;5. Folds: remediation commits on the contributor branch&lt;/h2&gt;
&lt;p&gt;Folds are maintainer commits pushed directly to the contributor branch. This
relies on &lt;code dir=&quot;auto&quot;&gt;maintainerCanModify&lt;/code&gt;, which is true by default on PRs from forks.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;One commit per fold.&lt;/strong&gt; Each landing-pass remediation is its own
single-purpose commit — never bundle two unrelated fixes into one commit,
and never split one logical fix across several. This is a hard rule, not a
preference: a mixed-purpose fold commit is what makes a later &lt;code dir=&quot;auto&quot;&gt;git revert&lt;/code&gt;
or bisect ambiguous.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Label the commit subject &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;(landing): ...&lt;/code&gt;&lt;/strong&gt; — a Conventional Commits
type, with &lt;code dir=&quot;auto&quot;&gt;landing&lt;/code&gt; as the scope. Pick the type from what the commit
actually touches: &lt;code dir=&quot;auto&quot;&gt;fix&lt;/code&gt; (product behaviour), &lt;code dir=&quot;auto&quot;&gt;test&lt;/code&gt; (tests/gates/baselines),
&lt;code dir=&quot;auto&quot;&gt;docs&lt;/code&gt; (prose, changelog, mission artifacts), &lt;code dir=&quot;auto&quot;&gt;chore&lt;/code&gt; (config, CI, tooling).
The scope keeps every fold greppable (&lt;code dir=&quot;auto&quot;&gt;git log --grep &apos;(landing)&apos;&lt;/code&gt;).&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Do not write &lt;code dir=&quot;auto&quot;&gt;landing fold: ...&lt;/code&gt;.&lt;/strong&gt; This runbook prescribed that label
until 2026-08-04 and it is &lt;strong&gt;rejected by the repo’s own commitlint gate&lt;/strong&gt;:
“landing fold” contains a space, so the Conventional Commits parser
extracts no type at all and every such commit fails both &lt;code dir=&quot;auto&quot;&gt;type-empty&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;subject-empty&lt;/code&gt;. It went unnoticed for several landing passes because
commitlint only lints commits &lt;strong&gt;in the PR range&lt;/strong&gt; — main’s own
&lt;code dir=&quot;auto&quot;&gt;landing fold:&lt;/code&gt; commits were never checked, so the violation only ever
surfaces on the PR that carries the folds. commitlint is not a
&lt;code dir=&quot;auto&quot;&gt;devDependency&lt;/code&gt;, so mirror CI’s own invocation (&lt;code dir=&quot;auto&quot;&gt;ci-quality.yml&lt;/code&gt;, the
&lt;code dir=&quot;auto&quot;&gt;commitlint&lt;/code&gt; step) and verify the whole batch before pushing:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;for&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;c&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; $(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;rev-list&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main..HEAD&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;); &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;do&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;npx&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--yes&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;@commitlint/cli@19.8.1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--config&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;commitlint.config.cjs&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--from&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$c&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;~1&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$c&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--verbose&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;echo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;FAILED: $(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;log&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--format=%s&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-n1&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$c&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Allowed types come from &lt;code dir=&quot;auto&quot;&gt;type-enum&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;commitlint.config.cjs&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;build chore ci docs feat fix lint perf plan refactor revert spec style test&lt;/code&gt;). There is no &lt;code dir=&quot;auto&quot;&gt;scope-enum&lt;/code&gt;, so &lt;code dir=&quot;auto&quot;&gt;(landing)&lt;/code&gt; needs no registration.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Explain every fold in the remediation summary comment (&lt;a href=&quot;#10-post-the-remediation-summary&quot;&gt;step 10&lt;/a&gt;).&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Typical folds: canonical-source fixes (the changelog lives in
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/&lt;/code&gt;), seam re-pins with dated rationale, retired-shim API
migrations, doc/contract artifact sync, and — by default — fixes for
&lt;strong&gt;pre-existing main breakage&lt;/strong&gt; the PR happens to surface (&lt;a href=&quot;#4-classify-every-red-check&quot;&gt;step 4&lt;/a&gt;).
The one red you do &lt;strong&gt;not&lt;/strong&gt; fold to green is a &lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt;-marked red-first
test: it is a deliberate open-P0 signal in the nightly and stays red until its
own product fix lands (ADR 2026-07-17-1).&lt;/p&gt;
&lt;h3 id=&quot;clean-history-compress-bookkeeping-keep-code-separate&quot;&gt;Clean history: compress bookkeeping, keep code separate&lt;/h3&gt;
&lt;p&gt;Recent practice over-corrected on this point: several contributor PRs were
landed &lt;strong&gt;fully squashed&lt;/strong&gt;, erasing the reviewable seam between distinct code
changes. That is not the target. When landing a contributor PR:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Compress bookkeeping/admin commits&lt;/strong&gt; — planning notes, fixups, “wip”,
formatting-only, mission-scaffolding, revert-of-own-typo — into the related
work commit they belong to.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Keep genuinely separate code/feature work as separate, reviewable
commits.&lt;/strong&gt; If the contributor made two distinct logical changes, land two
commits, not one.&lt;/li&gt;
&lt;li&gt;The goal is a readable history where each commit is one coherent change —
neither a single opaque squash nor 200 noise commits.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This governs the &lt;em&gt;contributor’s&lt;/em&gt; commits. Landing folds (above) are always
their own single-purpose &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;type&gt;(landing): ...&lt;/code&gt; commits regardless.&lt;/p&gt;
&lt;h3 id=&quot;regroup-a-very-long-history&quot;&gt;Regroup a very long history&lt;/h3&gt;
&lt;p&gt;For a very long history of status churn, tracer files and review artifacts, rebuild a
clean few-commit shape instead of replaying every commit. Branch off the current
&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, run &lt;code dir=&quot;auto&quot;&gt;git merge --squash &amp;#x3C;pr-branch&gt;&lt;/code&gt; (it integrates the branch and resolves
conflicts once, all staged), commit a snapshot, then &lt;code dir=&quot;auto&quot;&gt;git reset --mixed &amp;#x3C;main&gt;&lt;/code&gt; and
re-commit logical path groups: the code as reviewable commits plus one consolidated
&lt;code dir=&quot;auto&quot;&gt;chore(mission)&lt;/code&gt; commit for everything under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt;. The one guarantee
before you force-push is that the rebuilt tree is byte-identical to the old head
(&lt;code dir=&quot;auto&quot;&gt;git rev-parse HEAD^{tree}&lt;/code&gt; equal, &lt;code dir=&quot;auto&quot;&gt;git diff &amp;#x3C;old&gt; &amp;#x3C;new&gt;&lt;/code&gt; empty). Keep the
contributor’s authorship on their commits; maintainer landing fixes are separate,
maintainer-authored commits on top.&lt;/p&gt;
&lt;p&gt;The merge bar is the PR head going green, not each commit: an intermediate commit may
fail a gate that only reconciles at the tip (a regenerated docs index, say). Do not
rewrite history only to make every commit green.&lt;/p&gt;
&lt;h2 id=&quot;6-red-first-verification-for-bugfix-prs&quot;&gt;6. Red-first verification for bugfix PRs&lt;/h2&gt;
&lt;p&gt;A fix whose test is green before and after the fix captures nothing. Prove
the PR’s test actually witnesses the bug by swapping the pre-fix product file
back in:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;checkout&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream/main&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;product-file&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;PWHEADLESS&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;the&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;PR&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;s test&gt; -q     # MUST FAIL&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;git checkout HEAD -- &amp;#x3C;product-file&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;PWHEADLESS=1 uv run pytest &amp;#x3C;the PR&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;s&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;test&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-q&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;     &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# must pass again&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Post the result on the PR. If the test never goes red, the fold is a better
test — not a green checkmark.&lt;/p&gt;
&lt;h2 id=&quot;7-review-focus-areas-beyond-ci&quot;&gt;7. Review focus areas beyond CI&lt;/h2&gt;
&lt;p&gt;What the maintainer reads the diff for, beyond the checks:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Canonical sources&lt;/strong&gt; — does the change edit the source of truth, or a
generated mirror/agent copy? (Agent directories under &lt;code dir=&quot;auto&quot;&gt;.claude/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;.amazonq/&lt;/code&gt;, etc. are generated; sources live under &lt;code dir=&quot;auto&quot;&gt;packs/built-in/&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/&lt;/code&gt;.)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;SSOT / duplication&lt;/strong&gt; — does new code near-copy an existing canonical seam
or resolver? Justified divergence must be adjudicated explicitly (name the
contract difference), never assumed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Contract artifacts&lt;/strong&gt; — a new command or field on a versioned surface must
land in the machine contract (&lt;code dir=&quot;auto&quot;&gt;upstream_contract.json&lt;/code&gt;), the version
ledger, and the human docs together, in the same PR.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Scope-vs-spec&lt;/strong&gt; — an apparent scope surprise may be required by the
mission spec; check the FRs and constraints before flagging creep.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Error-handling nets&lt;/strong&gt; — best-effort helpers must catch the &lt;em&gt;actual&lt;/em&gt;
exception types their callees raise, not a guessed superset.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Terminology canon&lt;/strong&gt; — on any prose or doctrine touch, run the guard
locally: &lt;code dir=&quot;auto&quot;&gt;PWHEADLESS=1 uv run pytest tests/architectural/test_no_legacy_terminology.py -q&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;PR body style&lt;/strong&gt; — does the PR body lead with impact (what changes for a
user or operator), before architecture or test-strategy detail? See
&lt;a href=&quot;/development/how-to/review-gates/#pr-body-style-consumer-focused-bluf&quot;&gt;Review gates: PR body style&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Changelog update&lt;/strong&gt; — does a user-facing change carry a consumer-focused
entry as a fragment in &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&lt;/code&gt;, not an edit of
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt;? See
&lt;a href=&quot;/development/how-to/review-gates/#changelog-update-and-style&quot;&gt;Review gates: Changelog update and style&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;8-adversarial-squad-for-architectural-or-api-surface-prs&quot;&gt;8. Adversarial squad for architectural or API-surface PRs&lt;/h2&gt;
&lt;p&gt;For changes to versioned contracts or shared seams, dispatch profile-loaded
review lenses in parallel — for example &lt;code dir=&quot;auto&quot;&gt;architect-alphonso&lt;/code&gt; for design and
contract adherence, &lt;code dir=&quot;auto&quot;&gt;paula-patterns&lt;/code&gt; for SSOT and duplication — with
read-only access to the landing worktree.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Fold their findings — MAJOR, MINOR, and NOTE alike&lt;/strong&gt; (&lt;a href=&quot;#5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;step 5&lt;/a&gt;).
The default is to fix everything the squad surfaces, in this PR, while the
branch is open and the context is loaded. A MINOR or NOTE is cheap to fold now
and expensive to rediscover later; deferring it to a “someday” issue is how
easy fixes rot on a backlog and how the same finding gets re-raised on the next
pass. Do not triage-by-severity into fold-vs-defer — fold by default.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;File a follow-up issue only as the exception&lt;/strong&gt;, when folding is genuinely the
wrong call for one of three reasons: (a) the finding is &lt;strong&gt;highly impactful&lt;/strong&gt;
(it changes a contract, a shared seam or behaviour the PR does not own);
(b) it &lt;strong&gt;takes significant effort&lt;/strong&gt; (wide blast radius, many files, a refactor
that would swamp the review); or (c) it &lt;strong&gt;needs a significant operator
decision&lt;/strong&gt; — a spec, an ADR, or a ruling before any code moves. In those cases
file the issue the same day, parent it under the relevant functional epic, and
name it in the PR’s &lt;code dir=&quot;auto&quot;&gt;## Deferred&lt;/code&gt; section with the reason. Every other finding,
whatever its severity, is folded.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;delegate-remediation-to-subagents&quot;&gt;Delegate remediation to subagents&lt;/h3&gt;
&lt;p&gt;When a landing pass needs remediation beyond a one-line fold, delegate the
implementation to a profile-loaded subagent rather than hand-authoring it
inline — load the agent profile through the charter
(&lt;code dir=&quot;auto&quot;&gt;spec-kitty charter context --action implement --include agent-profile:&amp;#x3C;id&gt;&lt;/code&gt;,
or &lt;code dir=&quot;auto&quot;&gt;spec-kitty agent profile show &amp;#x3C;id&gt;&lt;/code&gt;), and apply model discipline:
implementation work routes to &lt;code dir=&quot;auto&quot;&gt;sonnet&lt;/code&gt;, review work routes to &lt;code dir=&quot;auto&quot;&gt;opus&lt;/code&gt;. The
maintainer’s job is to classify each red (&lt;a href=&quot;#4-classify-every-red-check&quot;&gt;step 4&lt;/a&gt;)
and adjudicate the result, not to write every fold by hand. This complements
the adversarial squad above — the squad finds and classifies, subagents
implement the fold, the maintainer adjudicates and lands it as one commit
(&lt;a href=&quot;#5-folds-remediation-commits-on-the-contributor-branch&quot;&gt;step 5&lt;/a&gt;).&lt;/p&gt;
&lt;p&gt;Mechanics that make a parallel pass work, learned on 2026-08-04 (24+ folds,
14 delegated agents):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Give every agent its own worktree and an explicit no-touch list.&lt;/strong&gt; Name
the files other in-flight agents hold. Without it, two agents edit
&lt;code dir=&quot;auto&quot;&gt;resolver.py&lt;/code&gt; and both cherry-picks conflict. Sequence anything that shares
a file; parallelise everything that does not.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agents commit in their own worktree and never push.&lt;/strong&gt; The maintainer
cherry-picks onto the landing branch. Because the worktrees share one object
store, &lt;code dir=&quot;auto&quot;&gt;git cherry-pick &amp;#x3C;sha&gt;&lt;/code&gt; works with no remote round-trip.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;cd&lt;/code&gt; into the landing worktree on every cherry-pick, and check the branch
before applying.&lt;/strong&gt; A shell whose working directory resets between commands
lands you in the &lt;strong&gt;primary checkout — which is on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;&lt;/strong&gt; — and a
cherry-pick there silently commits landing folds onto local &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. This
happened on the 2026-08-04 pass: three commits went onto &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; before the
branch name in git’s output gave it away. It is fully recoverable (nothing
was pushed; &lt;code dir=&quot;auto&quot;&gt;git reset --hard upstream/main&lt;/code&gt; restored it, and the commits
re-applied cleanly to the landing branch from the agent worktree), but only
because it was noticed immediately. Make it structural rather than vigilant:
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;landing-worktree&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;test&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;branch&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--show-current&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;)&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;&amp;#x3C;landing-branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;&amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;cherry-pick&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;sha&gt;...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
Re-check the fold count after each cherry-pick (&lt;code dir=&quot;auto&quot;&gt;git log --oneline &amp;#x3C;base&gt;..HEAD | wc -l&lt;/code&gt;)
— a count that resets to a small number means you are on the wrong branch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A revert pair cancels out — skip both and prove tree parity.&lt;/strong&gt; An agent
that self-corrects may leave &lt;code dir=&quot;auto&quot;&gt;X&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;Revert &quot;X&quot;&lt;/code&gt; plus a re-landed &lt;code dir=&quot;auto&quot;&gt;X&apos;&lt;/code&gt;.
Cherry-pick the net set, then prove nothing was lost:
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;diff&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;agent-branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;HEAD&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;the&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;files&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;that&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;owned&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# expect empty&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Convergence is the signal worth acting on.&lt;/strong&gt; When independent lenses
reproduce the same defect with live before/after output, treat it as
confirmed and fix it — do not re-derive. Conversely, a single lens’s
&lt;em&gt;proposed fix&lt;/em&gt; still needs checking: on 2026-08-04 two lenses proposed the
same one-line change and the implementer correctly rejected it, because that
line would have destroyed a legitimately-empty configured value. Brief
agents to &lt;strong&gt;verify the diagnosis before applying the prescription&lt;/strong&gt;, and to
stop and report if the code disagrees with the brief.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Instruct agents never to fabricate evidence.&lt;/strong&gt; A measurement they could
not take must be reported as not taken. A matrix row marked &lt;code dir=&quot;auto&quot;&gt;pending&lt;/code&gt; with a
reason is worth more than one marked &lt;code dir=&quot;auto&quot;&gt;pass&lt;/code&gt; without proof.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;9-push-discipline&quot;&gt;9. Push discipline&lt;/h2&gt;
&lt;p&gt;SSH is the preferred transport to GitHub, including for a force-push with lease:
use an SSH remote by default. Never push to &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;. If a permission prompt or safety
classifier refuses a push that follows these rules, stop and hand the push to the
operator.&lt;/p&gt;
&lt;p&gt;Before any force-push to a fork branch, check for commits you have not seen —
Copilot-review commits and parallel-session commits get cherry-picked, never
clobbered:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Fetch into an explicit remote-tracking ref — never rely on FETCH_HEAD.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;fetch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;fork-remote&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;branch&gt;:refs/remotes/&amp;#x3C;fork-remote&gt;/&amp;#x3C;branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;log&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;old-head&gt;..refs/remotes/&amp;#x3C;fork-remote&gt;/&amp;#x3C;branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--oneline&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# anything here? cherry-pick it first&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;LEASE_SHA&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;$(&lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;rev-parse&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;refs/remotes/&amp;#x3C;fork-remote&gt;/&amp;#x3C;branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;push&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;fork-remote&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;HEAD:refs/heads/&amp;#x3C;branch&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--force-with-lease=&amp;#x3C;branch&gt;:&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$LEASE_SHA&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Two lease lessons from the 2026-07-04 pass, both worth internalizing:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;A bare &lt;code dir=&quot;auto&quot;&gt;--force-with-lease&lt;/code&gt; fails with &lt;code dir=&quot;auto&quot;&gt;(stale info)&lt;/code&gt; on fork branches
you have never fetched&lt;/strong&gt; — the lease has no remote-tracking ref to compare
against locally. The explicit &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;branch&gt;:&amp;#x3C;sha&gt;&lt;/code&gt; form above is the standard
flow, not a workaround.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The lease sha must come from &lt;code dir=&quot;auto&quot;&gt;git rev-parse&lt;/code&gt;, never retyped from a
display.&lt;/strong&gt; Two pushes in the pass were rejected because a lease sha was
retyped from a 9-character abbreviated prefix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;rev-parse FETCH_HEAD&lt;/code&gt; is only valid immediately after fetching the ref
you mean.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;FETCH_HEAD&lt;/code&gt; is a single global file that &lt;em&gt;every&lt;/em&gt; fetch
overwrites, so a &lt;code dir=&quot;auto&quot;&gt;git fetch upstream main&lt;/code&gt; between the fork fetch and the
push silently substitutes main’s sha into the lease — producing a
&lt;code dir=&quot;auto&quot;&gt;(stale info)&lt;/code&gt; rejection that looks like “someone else pushed” when nothing
moved. This cost a rejected push on the 2026-08-04 pass. Fetch into an
explicit &lt;code dir=&quot;auto&quot;&gt;refs/remotes/&amp;#x3C;fork-remote&gt;/&amp;#x3C;branch&gt;&lt;/code&gt; and rev-parse that, as
above; it survives any number of intervening fetches.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;10-post-the-remediation-summary&quot;&gt;10. Post the remediation summary&lt;/h2&gt;
&lt;p&gt;After pushing folds, post one structured comment on the PR:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;the review verdict;&lt;/li&gt;
&lt;li&gt;each fold, with its why;&lt;/li&gt;
&lt;li&gt;squad verdicts, if a squad ran;&lt;/li&gt;
&lt;li&gt;local test evidence — counts, plus &lt;code dir=&quot;auto&quot;&gt;ruff&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt; results;&lt;/li&gt;
&lt;li&gt;pre-existing failures called out &lt;strong&gt;with the filed issue number&lt;/strong&gt;;&lt;/li&gt;
&lt;li&gt;the state: e.g. “watching CI; merge-ready on green”.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Contributor-education notes (for example, which file is the canonical
changelog) go in this comment too, addressed to the author.&lt;/p&gt;
&lt;h2 id=&quot;11-hand-off--the-operator-merges&quot;&gt;11. Hand-off — the operator merges&lt;/h2&gt;
&lt;p&gt;The operator merges. &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; merges through GitHub’s merge queue: the queue
tests each PR on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; plus the PRs ahead of it and rebase-merges it when the
required checks pass there, so a PR that is only behind &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; needs no manual
rebase and CI re-run. The queue does not resolve conflicts: a PR that conflicts
with &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, or with a PR ahead of it in the queue, cannot be queued or is
removed from the queue, and still needs a rebase. A landing pass asks once at
its start whether to queue the PR when it is merge-ready
(&lt;code dir=&quot;auto&quot;&gt;gh pr merge &amp;#x3C;N&gt; --auto&lt;/code&gt; adds it to the queue once its own checks pass); the
default is not to, and without an explicit yes for that run nobody but the
operator queues or merges. Do not push to a queued PR: a push removes it from
the queue and rebuilds every group behind it. The hand-off deliverable is:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;green CI;&lt;/li&gt;
&lt;li&gt;the PR ready for review (the author flipped it, or the operator told you to land
it while it was still a draft);&lt;/li&gt;
&lt;li&gt;the evidence trail on the PR;&lt;/li&gt;
&lt;li&gt;landing-order constraints stated explicitly — for example, a structural
cutover riding one PR forces an order on the rest of the pass.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;12-after-the-merge-remove-the-landing-worktree&quot;&gt;12. After the merge: remove the landing worktree&lt;/h2&gt;
&lt;p&gt;Once the operator merges, the landing worktree from
&lt;a href=&quot;#2-one-isolated-worktree-per-pr&quot;&gt;step 2&lt;/a&gt; and its local branch are left
behind. Remove them with &lt;code dir=&quot;auto&quot;&gt;doctor workspaces&lt;/code&gt;, not by hand:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;fetch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;origin&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;workspaces&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;workspaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--prune&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;A clone whose &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt; is a fork proves against the canonical repository
instead; &lt;code dir=&quot;auto&quot;&gt;upstream&lt;/code&gt; is the remote the steps above fetch the PR and &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; from
(#7214):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;fetch&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;workspaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--remote&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;doctor&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;workspaces&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--prune&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--remote&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;upstream&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;git fetch &amp;#x3C;remote&gt;&lt;/code&gt; first.&lt;/strong&gt; The check reads your local &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt;
ref (for example &lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt;) and never fetches. The remote is &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt;
unless &lt;code dir=&quot;auto&quot;&gt;--remote&lt;/code&gt; names another; the primary branch comes from that remote’s
&lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt;, or from a branch named &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;master&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;develop&lt;/code&gt;; when it cannot
be told, every worktree is unproven (set it with
&lt;code dir=&quot;auto&quot;&gt;git remote set-head &amp;#x3C;remote&gt; &amp;#x3C;branch&gt;&lt;/code&gt;). Only the named remote’s primary ref
is read, never another remote’s copy of the same commit. A blank value
(&lt;code dir=&quot;auto&quot;&gt;--remote &quot;$UNSET&quot;&lt;/code&gt;) is refused rather than falling back to &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt;, and a
name the clone does not configure exits 1 with the names it does have, so a
mistyped remote never reads as “nothing landed”. A clone with no remotes at all
reports &lt;code dir=&quot;auto&quot;&gt;unproven&lt;/code&gt; instead.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor workspaces&lt;/code&gt;&lt;/strong&gt; writes nothing. It gives every registered
worktree a verdict with a reason: landed, not landed, unproven, or
Mission-owned. “Landed” means the worktree’s commits are on
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt; and nothing uncommitted or running is in it. Merge
commits count. Rebase and squash merges count with git 2.38 or newer. The
report also lists the ignored files a removal would delete, such as &lt;code dir=&quot;auto&quot;&gt;.venv/&lt;/code&gt;
or &lt;code dir=&quot;auto&quot;&gt;.env&lt;/code&gt;. A remote name the repository does not configure is an error, not
an all-unproven report.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;--prune&lt;/code&gt;&lt;/strong&gt; removes only the landed worktrees, then their local branches.
It never uses &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;. Every step it takes discharges the proof obligations
of &lt;a href=&quot;/adr/4.x/2026-11-06-1-a-destructive-git-operation-discharges-named-proof-obligations/&quot;&gt;ADR 2026-11-06-1&lt;/a&gt;.
It checks each worktree again right before it
removes it, against the same &lt;code dir=&quot;auto&quot;&gt;--remote&lt;/code&gt;, and deletes the branch only while it
still points at the tip it proved landed (a compare-and-swap), so a branch
that moves in the meantime is kept and reported as &lt;code dir=&quot;auto&quot;&gt;BRANCH_MOVED&lt;/code&gt;. Before it
removes anything it reads the worktree’s &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; reflog and the branch reflog,
and records every commit that only those still reached
(see &lt;a href=&quot;#restore-a-removed-worktree&quot;&gt;Restore a removed worktree&lt;/a&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; is unchanged: it still removes only unregistered husks.&lt;/p&gt;
&lt;h3 id=&quot;what---prune-never-removes&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;--prune&lt;/code&gt; never removes&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;a worktree with uncommitted changes or untracked files, including edits
hidden by &lt;code dir=&quot;auto&quot;&gt;git update-index --assume-unchanged&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;--skip-worktree&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a worktree with a rebase, merge, cherry-pick, revert or bisect in progress
(&lt;code dir=&quot;auto&quot;&gt;OPERATION_IN_PROGRESS&lt;/code&gt;; a Mission lane mid-rebase is reported as
Mission-owned);&lt;/li&gt;
&lt;li&gt;a worktree with a nested repository (a &lt;code dir=&quot;auto&quot;&gt;.git&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.hg&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;.jj&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.svn&lt;/code&gt;
entry, or a bare or renamed git directory) under an ignored path;&lt;/li&gt;
&lt;li&gt;a locked worktree;&lt;/li&gt;
&lt;li&gt;a worktree whose committed content is not on &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;a worktree a running process of yours is standing in;&lt;/li&gt;
&lt;li&gt;Mission lane and coordination worktrees (reported only; &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; owns them);&lt;/li&gt;
&lt;li&gt;the main worktree, and the worktree you run the command from.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Some worktrees are kept and reported for you to decide:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No commits of its own&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;NO_OWN_COMMITS&lt;/code&gt;). The branch tip is on
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt;, but its reflog shows no commit made on it. A pull, a
fast-forward merge or a rebase is not a commit of its own. Remove it by
hand if you are done with it. A branch with no reflog at all is unproven
(&lt;code dir=&quot;auto&quot;&gt;REFLOG_MISSING&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Detached worktrees outside &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;DETACHED_OUTSIDE_WORKTREES&lt;/code&gt;)
are never assessed. These are scratch checkouts another spec-kitty command
made and owns. They appear only in the &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;known-gaps&quot;&gt;Known gaps&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Linux only.&lt;/strong&gt; On macOS and Windows, running processes cannot be checked.
Every candidate is then reported as unproven, and &lt;code dir=&quot;auto&quot;&gt;--prune&lt;/code&gt; removes nothing
(#7216). For a worktree unproven only for that reason, the report prints the
hand commands, with paths quoted for your shell. Run them only after you have
checked that nothing runs in the worktree and its content is on
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt;: &lt;code dir=&quot;auto&quot;&gt;git worktree remove &amp;#x3C;path&gt;&lt;/code&gt; (never &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;), then
&lt;code dir=&quot;auto&quot;&gt;git update-ref refs/spec-kitty/discarded/&amp;#x3C;branch&gt; &amp;#x3C;sha&gt; &apos;&apos;&lt;/code&gt; to keep the tip
(the empty old value makes it refuse to overwrite an earlier record), then
&lt;code dir=&quot;auto&quot;&gt;git branch -D &amp;#x3C;branch&gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;git 2.38 or newer for rebase and squash merges.&lt;/strong&gt; Older git cannot prove
them, so such a worktree is reported as unproven and kept.&lt;/li&gt;
&lt;li&gt;Processes of other users are not detected. Nor are your own processes whose
working directory cannot be read; the command prints how many it could not
inspect. Close editors and shells in the worktree first.&lt;/li&gt;
&lt;li&gt;Ignored files (for example &lt;code dir=&quot;auto&quot;&gt;.venv/&lt;/code&gt;, or an ignored &lt;code dir=&quot;auto&quot;&gt;.env&lt;/code&gt;) are deleted with
the worktree. The report lists them first.&lt;/li&gt;
&lt;li&gt;A stale &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt; usually only hides a merge. It can also vouch for
content that was later rewritten off the remote’s primary branch. That is
why &lt;code dir=&quot;auto&quot;&gt;--prune&lt;/code&gt; keeps any tip that no local branch or tag reaches (see below).&lt;/li&gt;
&lt;li&gt;Commits that only the worktree’s HEAD reflog or the branch reflog still
reach (for example a commit made while detached and then left) lose that
record with the removal (#7211).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;a-merge-that-happens-after-the-session-ends&quot;&gt;A merge that happens after the session ends&lt;/h3&gt;
&lt;p&gt;The operator often merges after the landing session is over. Nothing has to
remember the worktree. On Linux, the next &lt;code dir=&quot;auto&quot;&gt;git fetch &amp;#x3C;remote&gt;&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor workspaces --prune&lt;/code&gt; (plus &lt;code dir=&quot;auto&quot;&gt;--remote &amp;#x3C;name&gt;&lt;/code&gt; when the
canonical repository is not &lt;code dir=&quot;auto&quot;&gt;origin&lt;/code&gt;), from any later session, finds it landed
and removes it. Until then it is reported as not landed and kept. On
macOS and Windows, remove it by hand (see &lt;a href=&quot;#known-gaps&quot;&gt;Known gaps&lt;/a&gt;).&lt;/p&gt;
&lt;h3 id=&quot;restore-a-removed-worktree&quot;&gt;Restore a removed worktree&lt;/h3&gt;
&lt;p&gt;Every removal prints its recreate command:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Removed .worktrees/pr-&amp;#x3C;N&gt;-landing (branch pr-&amp;#x3C;N&gt;-local at 1a2b3c4d5e6f)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;recreate: git branch pr-&amp;#x3C;N&gt;-local 1a2b3c4d5e6f...&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;tip kept at refs/spec-kitty/discarded/pr-&amp;#x3C;N&gt;-local&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;Branch: &lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;branch&gt; &amp;#x3C;sha&gt;&lt;/code&gt;, then
&lt;code dir=&quot;auto&quot;&gt;git worktree add .worktrees/pr-&amp;#x3C;N&gt;-landing &amp;#x3C;branch&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Branch kept (the report prints a &lt;code dir=&quot;auto&quot;&gt;branch kept&lt;/code&gt; line, for example because the
branch moved or is the primary branch): the recreate command is
&lt;code dir=&quot;auto&quot;&gt;git worktree add &amp;#x3C;path&gt; &amp;#x3C;branch&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Branch checked out in another worktree: git refuses a second checkout, so
the recreate command is &lt;code dir=&quot;auto&quot;&gt;git worktree add --detach &amp;#x3C;path&gt; &amp;#x3C;sha&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;Detached worktree: &lt;code dir=&quot;auto&quot;&gt;git worktree add --detach &amp;#x3C;path&gt; &amp;#x3C;sha&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;When no local branch or tag reaches the tip (remote-tracking refs do not
count), the tip is also kept under &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/&lt;/code&gt;: at
&lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/&amp;#x3C;branch&gt;&lt;/code&gt; for a branch (with a suffix such as
&lt;code dir=&quot;auto&quot;&gt;@&amp;#x3C;short-sha&gt;&lt;/code&gt; when an earlier tip already holds that name), and at
&lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/detached/&amp;#x3C;sha&gt;&lt;/code&gt; for a detached worktree. Use the
ref printed on the &lt;code dir=&quot;auto&quot;&gt;tip kept at&lt;/code&gt; line:
&lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;branch&gt; &amp;#x3C;ref printed on the tip kept at line&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Partly removed.&lt;/strong&gt; When git deleted part of a worktree and then failed (for
example on a read-only directory under &lt;code dir=&quot;auto&quot;&gt;.venv/&lt;/code&gt;), the report prints a
&lt;code dir=&quot;auto&quot;&gt;partly removed&lt;/code&gt; line, keeps the branch and exits 1. Run
&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor workspaces --fix&lt;/code&gt; to clear the leftover directory.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;A commit that only a destroyed reflog still reached gets its own line and its
own ref:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;reflog-only commit kept at refs/spec-kitty/discarded/reflog/&amp;#x3C;sha&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;git worktree remove&lt;/code&gt; deletes the worktree &lt;code dir=&quot;auto&quot;&gt;HEAD&lt;/code&gt; reflog and
&lt;code dir=&quot;auto&quot;&gt;git branch -D&lt;/code&gt; deletes the branch reflog, so a commit made while the worktree
was detached, or one dropped with &lt;code dir=&quot;auto&quot;&gt;git reset --hard&lt;/code&gt;, would otherwise be
reachable from nothing and could be collected by &lt;code dir=&quot;auto&quot;&gt;git gc&lt;/code&gt;. The prune records
it under &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/discarded/reflog/&amp;#x3C;sha&gt;&lt;/code&gt; &lt;strong&gt;before&lt;/strong&gt; it removes the
worktree; restore it with
&lt;code dir=&quot;auto&quot;&gt;git branch &amp;#x3C;name&gt; refs/spec-kitty/discarded/reflog/&amp;#x3C;sha&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Two things are deliberately not recorded: a commit that a local branch, tag
or &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/&lt;/code&gt; ref still reaches (a remote-tracking ref does not count:
the next fetch can rewrite it), and one the prune can &lt;strong&gt;prove&lt;/strong&gt; is already on &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;remote&gt;/&amp;#x3C;primary&gt;&lt;/code&gt;.
“Prove” is narrow: replaying each commit that would be lost onto the primary
must change nothing, byte for byte (whitespace included, so &lt;code dir=&quot;auto&quot;&gt;git cherry&lt;/code&gt;’s
patch-id is not used), and none of them may be a merge, a root or an empty
commit. That proof is what keeps a rebase landing from adding a ref per
superseded commit. Anything it cannot prove is recorded, so a merge commit
in that position always is: no patch carries a merge’s own resolution. The &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; payload names the refs in the
&lt;code dir=&quot;auto&quot;&gt;kept_commits&lt;/code&gt; key of each &lt;code dir=&quot;auto&quot;&gt;pruned&lt;/code&gt; entry. If a ref cannot be written, the
prune removes nothing and reports it. A failed &lt;code dir=&quot;auto&quot;&gt;tip kept at&lt;/code&gt; record happens after
the removal: the worktree is gone and the output says the branch was kept.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;upgrade-leaves-landing-worktrees-alone&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;upgrade&lt;/code&gt; leaves landing worktrees alone&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt; no longer writes or commits into a non-Mission worktree
under &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; unless you name it with &lt;code dir=&quot;auto&quot;&gt;--include-worktree &amp;#x3C;path&gt;&lt;/code&gt;
(repeatable) or pass &lt;code dir=&quot;auto&quot;&gt;--all-worktrees&lt;/code&gt;. Its preview lists every worktree and
what will happen to it, so a landing worktree is never committed into by
surprise.&lt;/p&gt;
&lt;h2 id=&quot;13-follow-up-hygiene&quot;&gt;13. Follow-up hygiene&lt;/h2&gt;
&lt;p&gt;Most of what a landing pass discovers should be &lt;strong&gt;folded, not filed&lt;/strong&gt; — see the
fold-first default in &lt;a href=&quot;#8-adversarial-squad-for-architectural-or-api-surface-prs&quot;&gt;step 8&lt;/a&gt;.
What genuinely cannot be folded — a finding that is highly impactful, takes
significant effort, or needs a significant operator decision — gets a tracked home &lt;strong&gt;the
same day&lt;/strong&gt;: filed, labeled, and parented under a functional epic (never a meta
rollup). New issues get processed by a triage pass immediately, so the next
landing pass starts from a clean queue.&lt;/p&gt;
&lt;h2 id=&quot;pausing-a-prs-ci-prpause-ci&quot;&gt;Pausing a PR’s CI (&lt;code dir=&quot;auto&quot;&gt;pr:pause-ci&lt;/code&gt;)&lt;/h2&gt;
&lt;p&gt;When many PRs are rebased at once, Actions queues far more work than it can run. Label every
PR that is not being landed &lt;code dir=&quot;auto&quot;&gt;pr:pause-ci&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Heavy jobs skip.&lt;/strong&gt; The root job of each PR workflow (&lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;generate-matrix&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;lint&lt;/code&gt;
and so on) carries &lt;code dir=&quot;auto&quot;&gt;!contains(github.event.pull_request.labels.*.name, &apos;pr:pause-ci&apos;)&lt;/code&gt;, so
everything downstream skips too.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The PR cannot merge.&lt;/strong&gt; The required gates (&lt;code dir=&quot;auto&quot;&gt;router gate&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;CI Modules gate&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;Clean install verification&lt;/code&gt;) still run, because a skipped required check passes, and fail
with “CI is paused on this PR by the pr:pause-ci label; remove the label to run CI.”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;It takes effect at once.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;.github/workflows/pr-pause-ci.yml&lt;/code&gt; cancels the PR’s queued and
in-progress runs and posts a failing check under each required gate name, so a PR that was
already green stops being mergeable.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;To resume, remove the label. CI Router, CI Modules and CI Quality, the workflows behind the
required gates, also trigger on &lt;code dir=&quot;auto&quot;&gt;labeled&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;unlabeled&lt;/code&gt;, so removing the label starts their full
run on the PR’s current head, with no push, also when the PR was pushed while labeled. Adding the
label starts them too: the gates fail again with the pause message, and the new run cancels the
one in flight. The pause workflow re-runs only the other runs it canceled (Packs, Contracts and so
on); they started before the label, so they run in full. A run that started while the PR was
labeled replays that label and pauses again, so an optional workflow pushed under the label stays
paused until the next push. If the PR’s head moved after the label came off (you pushed), the
re-run is skipped: the new head’s runs are current.&lt;/p&gt;
&lt;p&gt;Adding or removing any other label also starts those three workflows, because GitHub cannot filter
a &lt;code dir=&quot;auto&quot;&gt;pull_request&lt;/code&gt; trigger by label name. So does any label change on a closed PR. Such a run is a
no-op:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;every job skips;&lt;/li&gt;
&lt;li&gt;the required gate never posts under its required name, because a skipped job still posts a
check run and a skipped required check passes. In a no-op run the gate’s &lt;code dir=&quot;auto&quot;&gt;name:&lt;/code&gt; expression
differs from the required name, and GitHub posts a skipped job under the raw text of that
expression (seen on #7047), so the row reads &lt;code dir=&quot;auto&quot;&gt;(github.event.action == &apos;labeled&apos; || ...)&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;the run has its own concurrency group, so it never cancels the real run;&lt;/li&gt;
&lt;li&gt;the CI Aggregate run it triggers skips every job, and the fleet verdict does not read it as
evidence.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The skipped jobs still post check runs under their usual names (&lt;code dir=&quot;auto&quot;&gt;ruff (lint + format)&lt;/code&gt;, the module
shards and so on), so after a label change the PR’s checks list can show those rows as skipped over
a real result. Read the three required gates and the fleet &lt;code dir=&quot;auto&quot;&gt;[ci]&lt;/code&gt; comment; they are not masked.&lt;/p&gt;
&lt;p&gt;For the full queue-recovery sequence, see &lt;a href=&quot;/development/how-to/unclog-ci/&quot;&gt;Pull the safety cord&lt;/a&gt;.&lt;/p&gt;
&lt;h2 id=&quot;gotchas&quot;&gt;Gotchas&lt;/h2&gt;
&lt;p&gt;Field notes from the 2026-07-04 landing pass. Where the friction has since
been fixed, the end-state is stated instead of the trap.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Changelog entries are fragments.&lt;/strong&gt; A PR adds &lt;code dir=&quot;auto&quot;&gt;docs/changelog/unreleased/&amp;#x3C;id&gt;.&amp;#x3C;section&gt;.md&lt;/code&gt;
and never edits &lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt; (the canonical file; the root
&lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.github/CHANGELOG.md&lt;/code&gt; are symlinks to it). The release
assembles the fragments into &lt;code dir=&quot;auto&quot;&gt;[Unreleased]&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;--force-with-lease&lt;/code&gt; on never-fetched fork branches.&lt;/strong&gt; See
&lt;a href=&quot;#9-push-discipline&quot;&gt;step 9&lt;/a&gt;: use the explicit &lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;branch&gt;:&amp;#x3C;sha&gt;&lt;/code&gt; lease form,
and take the sha from &lt;code dir=&quot;auto&quot;&gt;git rev-parse&lt;/code&gt; — never retype it from an
abbreviated display.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Pre-existing main breakage surfaces mid-pass.&lt;/strong&gt; One broken contract on
main (#2339: dotted &lt;code dir=&quot;auto&quot;&gt;migration_id&lt;/code&gt; vs the dry-run JSON contract) turned
local runs red on &lt;em&gt;every&lt;/em&gt; rebased branch in the pass. The default is to
&lt;strong&gt;fold the fix&lt;/strong&gt; (&lt;a href=&quot;#4-classify-every-red-check&quot;&gt;step 4&lt;/a&gt;) — that clears main
and every rebased branch inherits the green. When you &lt;em&gt;can’t&lt;/em&gt; fold (a
&lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt;-marked red-first test, or a mission-scope fix), file early; the
filed issue is what lets subsequent PRs skip re-reproducing it.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Saturated tolerance bands trip on the next legitimate change.&lt;/strong&gt; The CLI
visible-count census sat at the top of its band, so the next legitimate
command (#2338) tripped it. A saturated band needs a re-pin with a dated
rationale — e.g. the 2026-07-04 re-pin at 236 visible (tolerance 212–259)
in &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_check_cli_reference_freshness.py&lt;/code&gt;; the current values
live in that test, not here. That re-pin-in-the-same-PR pattern is the
model for the second bin of &lt;a href=&quot;#4-classify-every-red-check&quot;&gt;step 4&lt;/a&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Seam completeness gates are invisible to contributors.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;tasks_*.py&lt;/code&gt;
modules under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/&lt;/code&gt; are found on disk, so no
test file keeps a hand list of them. A moved or new symbol still needs its
re-export block in &lt;code dir=&quot;auto&quot;&gt;tasks_move_task.py&lt;/code&gt; (for a move-task seam) and in
&lt;code dir=&quot;auto&quot;&gt;agent/tasks.py&lt;/code&gt;, and a patch must target the module whose globals the call
reads (see the rule in the &lt;code dir=&quot;auto&quot;&gt;tasks_move_task_gates.py&lt;/code&gt; module docstring). Three
tests catch a miss: &lt;code dir=&quot;auto&quot;&gt;test_tasks_compat_surface.py&lt;/code&gt; (a re-export that is a copy),
&lt;code dir=&quot;auto&quot;&gt;test_tasks_move_task_seams.py&lt;/code&gt; (a missing re-export on &lt;code dir=&quot;auto&quot;&gt;tasks_move_task&lt;/code&gt;) and
&lt;code dir=&quot;auto&quot;&gt;test_tasks_patch_targets_live.py&lt;/code&gt; (a patch that intercepts nothing). A new
&lt;code dir=&quot;auto&quot;&gt;tasks_move_task_*.py&lt;/code&gt; module must also join the two scan lists in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_exemption_registry_ratchet.py&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_no_write_side_rederivation.py&lt;/code&gt;. Expect this as a fold
on PRs that touch decomposed command modules.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;CI-only architectural gates land late.&lt;/strong&gt; Repo-wide gates (terminology,
shim retirement, seam boundaries) run in the architectural battery: the
always-on &lt;code dir=&quot;auto&quot;&gt;architectural fast gates (ratchet/census, always-on)&lt;/code&gt; job and the
two &lt;code dir=&quot;auto&quot;&gt;architectural battery (heavy, code-scoped)&lt;/code&gt; legs (&lt;code dir=&quot;auto&quot;&gt;1/2&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;2/2&lt;/code&gt;). A PR
can pass every module shard and still fail in a heavy leg later. Run the
specific &lt;code dir=&quot;auto&quot;&gt;tests/architectural/&lt;/code&gt; gate files your diff implicates on the rebased
tip before declaring a branch green; do not sweep the whole directory
(&lt;code dir=&quot;auto&quot;&gt;NO_FULL_HEAVY_SUITES_IN_MISSION&lt;/code&gt;, see
&lt;a href=&quot;/development/reference/known-friction-points/&quot;&gt;known friction points&lt;/a&gt;).&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Shard path-filters mask pre-existing failures.&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;changes&lt;/code&gt; filter
skips shards such as &lt;code dir=&quot;auto&quot;&gt;module-tests (cli shard 1/2)&lt;/code&gt; on PRs that do not touch
those paths, so
a pre-existing red only surfaces on the first PR that does — the innocent
PR wears the failure. Classify it as pre-existing (bin three of
&lt;a href=&quot;#4-classify-every-red-check&quot;&gt;step 4&lt;/a&gt;), not as the PR’s defect.
&lt;strong&gt;Your own folds trigger this too:&lt;/strong&gt; a fold that touches a new path un-skips
that path’s shard, so the pass surfaces reds the PR never caused. On
2026-08-04 a fold under &lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/&lt;/code&gt; un-skipped &lt;code dir=&quot;auto&quot;&gt;fast-tests-agent&lt;/code&gt;
(the then-current job name; the agent tests now run in the &lt;code dir=&quot;auto&quot;&gt;agent&lt;/code&gt; module row of &lt;code dir=&quot;auto&quot;&gt;ci-modules.yml&lt;/code&gt;)
and exposed a golden-contract drift that reproduced cleanly on
&lt;code dir=&quot;auto&quot;&gt;abca7ec96&lt;/code&gt;. Re-classify after each batch of folds, not only at the start.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;File-scoped linters lint the whole file, not your diff.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;markdownlint&lt;/code&gt;
runs over &lt;em&gt;changed files&lt;/em&gt;, so editing one line of a long-lived document
subjects its entire pre-existing violation set to the gate. Touching
&lt;code dir=&quot;auto&quot;&gt;docs/changelog/CHANGELOG.md&lt;/code&gt; surfaced ~21 pre-existing &lt;code dir=&quot;auto&quot;&gt;MD049&lt;/code&gt; findings
spread across the file. Expect this on any changelog or large-doc fold, and
budget for fixing the file rather than only your lines. Run the repo’s own
markdownlint invocation (see the informational step in the &lt;code dir=&quot;auto&quot;&gt;uv-lock&lt;/code&gt; job of &lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-router.yml&lt;/code&gt;)
rather than a default config.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Moving or adding a test file trips completeness baselines.&lt;/strong&gt; New or
relocated test files must join their registries in the &lt;em&gt;same commit&lt;/em&gt; as the
move, each with a dated rationale. Search the repo for the new filename
before committing. Never key an allowlist by line number or whole file
(banned by #2077 / &lt;code dir=&quot;auto&quot;&gt;DIRECTIVE_041&lt;/code&gt;) — use content descriptors.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Verify architectural gates from a non-dot path.&lt;/strong&gt; Gates that walk the tree
can silently skip dot-prefixed path segments, so a run from
&lt;code dir=&quot;auto&quot;&gt;.worktrees/…&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;.claude/worktrees/…&lt;/code&gt; can report a false green. Confirm
from a plain checkout before declaring a gate satisfied:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;worktree&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;add&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/verify-&amp;#x3C;N&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;sha&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/verify-&amp;#x3C;N&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;PWHEADLESS&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;1&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pytest&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tests/architectural/&amp;#x3C;gate&gt;.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-q&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A frozen-contract drift with &lt;code dir=&quot;auto&quot;&gt;missing: []&lt;/code&gt; means flags were &lt;em&gt;added&lt;/em&gt;, not
removed.&lt;/strong&gt; Read the direction before acting: extras with nothing missing is
a pin that was never joined when a feature shipped, so the fix is to re-pin
with a dated rationale. Never remove a shipped flag to satisfy a stale pin —
that smuggles a breaking change into a landing pass. Trace each addition
(&lt;code dir=&quot;auto&quot;&gt;git log -S&apos;--flag-name&apos; -- src/&lt;/code&gt;) and confirm it predates the merge-base
before re-pinning.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Never green-wash a red by “updating the test”.&lt;/strong&gt; Twice on the 2026-08-04
pass the obvious read — new gating narrowed a payload, so the assertion is
stale — was wrong: the rendered output was byte-identical on both sides and
the real defect was a product bug (a &lt;code dir=&quot;auto&quot;&gt;str.replace&lt;/code&gt; deleting a section header
along with its body). Prove the assertion is wrong &lt;em&gt;before&lt;/em&gt; changing it, by
showing the expected behaviour genuinely changed. If the test is right, fix
the product even when that is the larger job.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Run doc scripts as modules.&lt;/strong&gt; The docs scripts import &lt;code dir=&quot;auto&quot;&gt;scripts.docs.*&lt;/code&gt; as a
package; run &lt;code dir=&quot;auto&quot;&gt;uv run python -m scripts.docs.&amp;#x3C;x&gt;&lt;/code&gt;, never the bare
&lt;code dir=&quot;auto&quot;&gt;scripts/docs/&amp;#x3C;x&gt;.py&lt;/code&gt; path, which crashes with &lt;code dir=&quot;auto&quot;&gt;ModuleNotFoundError: scripts&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.docs.check_docs_freshness&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--ci&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Regenerating the CLI reference.&lt;/strong&gt; The canonical reference is
&lt;code dir=&quot;auto&quot;&gt;docs/api/cli-commands.md&lt;/code&gt;; pass the outputs explicitly:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts.docs.build_cli_reference&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--output&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;docs/api/cli-commands.md&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent-output&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;docs/api/agent-subcommands.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Per-worktree venv rebuild.&lt;/strong&gt; The first &lt;code dir=&quot;auto&quot;&gt;uv run&lt;/code&gt; in a fresh landing
worktree rebuilds the virtualenv (~40 s + disk). Budget for it; do not
debug it.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Do NOT recapture shard-timings during a landing (#5189, #5536).&lt;/strong&gt; When a PR
adds or removes tests in a registry module, that module’s committed count and
durations in &lt;code dir=&quot;auto&quot;&gt;.github/ci-shard-timings.json&lt;/code&gt; no longer match live collection, so
the exact-count checks in &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_module_length_agreement.py&lt;/code&gt;
(for example &lt;code dir=&quot;auto&quot;&gt;test_charter_agrees_with_live_collection&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;test_every_registry_module_agrees_with_live_collection&lt;/code&gt;) drift. This is the one
count-pinning anchor the general “recapture a drifted count anchor” advice does
&lt;strong&gt;not&lt;/strong&gt; apply to, for any module. Per PR the drift is a warning from the
module-tests select step, not a failure, and those two tests are skipped (#7288). The strict exact-count gate lives in
&lt;code dir=&quot;auto&quot;&gt;ci-shard-recapture.yml&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;schedule&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;workflow_dispatch&lt;/code&gt;, no PR/push trigger, so
it cannot run on a PR or block merge). Its &lt;code dir=&quot;auto&quot;&gt;recapture-shard-timings&lt;/code&gt; job counts
every module’s tests on each scheduled run on the primary branch (&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;),
recaptures the drifted ones within a 70-minute budget (the rest are deferred to
the next run) and opens or refreshes one pull request on &lt;code dir=&quot;auto&quot;&gt;ci/recapture-shard-timings&lt;/code&gt;. Until that proposal
merges, the strict check is red on the scheduled run; that is the accepted
window. So note the drift as automation-owned in the hand-off and move on: a local
recapture of a large module takes 18-30 minutes of machine-specific measurement
for a gate that cannot block the PR. If the scheduled job captured but could not
push, the publish step names the token secret to replace (see #5624). See
&lt;a href=&quot;/development/reference/ci-gate-mechanics/#scheduled-shard-timings-recapture&quot;&gt;Scheduled shard-timings recapture&lt;/a&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A &lt;code dir=&quot;auto&quot;&gt;docs(landing)&lt;/code&gt; fold that edits a &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; mission dossier reds
&lt;code dir=&quot;auto&quot;&gt;archive freeze&lt;/code&gt;.&lt;/strong&gt; Archived mission dossiers are frozen byte-identical
(&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_archive_root_byte_identical.py&lt;/code&gt;, the always-on
&lt;code dir=&quot;auto&quot;&gt;archive freeze&lt;/code&gt; job; this is the #4260 “rewriting archived dossiers unjudged”
class). If a squad flags that a &lt;em&gt;cited&lt;/em&gt; archived contract now contradicts
shipped behavior, do &lt;strong&gt;not&lt;/strong&gt; edit the frozen dossier — record the supersession
in the &lt;strong&gt;live&lt;/strong&gt; code that cites it (the resolver docstring), which is the
correct place to overturn a frozen snapshot’s stale claims. Reproduce the gate
locally before pushing any fold that touches &lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt;.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A script that only a post-merge workflow runs is not exercised by PR CI.&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;ci-aggregate.yml&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;workflow_run&lt;/code&gt;-triggered. It runs for pull requests too, but
from the default-branch checkout, so a PR’s change to that workflow, or to a
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/*&lt;/code&gt; file it calls, is first exercised after the merge, and its check
does not attach to the PR head. When a PR edits such a script, run it the way the
workflow does before merge: &lt;code dir=&quot;auto&quot;&gt;python3 scripts/ci/&amp;#x3C;name&gt;.py&lt;/code&gt; from the repository root
with &lt;code dir=&quot;auto&quot;&gt;PYTHONPATH&lt;/code&gt; unset, and confirm it starts. A direct-run script must insert the
repository root on &lt;code dir=&quot;auto&quot;&gt;sys.path&lt;/code&gt; before importing &lt;code dir=&quot;auto&quot;&gt;scripts.*&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;kernel.*&lt;/code&gt; (see
&lt;code dir=&quot;auto&quot;&gt;scripts/ci/select_source_artifacts.py&lt;/code&gt;). Add a test that runs it as a subprocess.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Formatting an excluded file is a companion change.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;[tool.ruff.format].exclude&lt;/code&gt;
in &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; is a shrink-only list of files with formatter debt. Format only
with &lt;code dir=&quot;auto&quot;&gt;uv run --frozen ruff format --force-exclude &amp;#x3C;files&gt;&lt;/code&gt; (or check with
&lt;code dir=&quot;auto&quot;&gt;make format-check-files FILES=&amp;#x3C;paths&gt;&lt;/code&gt;). If you deliberately format a listed file
clean, its entry is stale: remove it in the same commit, and run
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_ruff_format_exclude_ratchet.py&lt;/code&gt; after the reformat, not
only before. A whole-repo &lt;code dir=&quot;auto&quot;&gt;ruff format --check .&lt;/code&gt; skips excluded files, so it does
not catch the stale entry.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Docs checks that fail only in CI.&lt;/strong&gt; The frontmatter &lt;code dir=&quot;auto&quot;&gt;description&lt;/code&gt; of a published page
must be 50 to 180 characters (&lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_seo.py&lt;/code&gt;; the docsite build’s
frontmatter gate refuses one over 180), and a
changelog entry over 1,200 characters fails &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_changelog_style.py&lt;/code&gt;.
The retrieval index stores the description, but the bot regenerates it after merge,
so do not regenerate it in the PR. A new ADR for a governance or process decision goes in
&lt;code dir=&quot;auto&quot;&gt;docs/adr/4.x/YYYY-MM-DD-N-&amp;#x3C;slug&gt;.md&lt;/code&gt; with status Accepted; check the day’s highest
&lt;code dir=&quot;auto&quot;&gt;-N-&lt;/code&gt; on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; first. Markdownlint is advisory in CI, so do not spend landing time
on a file’s pre-existing findings.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;A PR-landed lanes Mission keeps its evidence window on a branch you are about to
delete (#6780).&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;accept --mode pr --merge-commit &amp;#x3C;sha&gt;&lt;/code&gt; never runs
&lt;code dir=&quot;auto&quot;&gt;spec-kitty consolidate&lt;/code&gt;, so nothing records how each lane landed, and the
implementation-evidence gate windows each work package on
&lt;code dir=&quot;auto&quot;&gt;planning_commit..&amp;#x3C;lane branch&gt;&lt;/code&gt;. Prune the lane branches after the acceptance, not
between the PR merge and it — or, &lt;strong&gt;for a Mission that landed through a pull request
merge commit (not a squash)&lt;/strong&gt;, keep &lt;code dir=&quot;auto&quot;&gt;--merge-commit&lt;/code&gt; on every re-run: with the verified
landing commit supplied, a lane whose branch ref is truly absent is judged on
&lt;code dir=&quot;auto&quot;&gt;landing^1..landing&lt;/code&gt; — the PR’s merge commit on the target, not a lane consolidation —
that is, the PR’s own side of the merge, so unrelated work that reached the target first
never counts. The planning commit must sit on the merged-in side of that merge. A work
package whose &lt;code dir=&quot;auto&quot;&gt;owned_files&lt;/code&gt; overlap another approved work package’s is refused
&lt;code dir=&quot;auto&quot;&gt;IMPLEMENTATION_UNREADABLE&lt;/code&gt; (the merge alone cannot attribute the change): restore the
lane branch from &lt;code dir=&quot;auto&quot;&gt;refs/spec-kitty/lane-tip/&amp;#x3C;branch&gt;&lt;/code&gt; or the PR’s head and re-run. A
squash landing cannot use this path, and a branch ref that exists but cannot be read
refuses rather than falling back. &lt;strong&gt;Residual:&lt;/strong&gt; a Mission whose corpus was rebased first
(a rebased stack) shows only changes up to the corpus commit on the PR side, so its work
packages refuse &lt;code dir=&quot;auto&quot;&gt;IMPLEMENTATION_MISSING&lt;/code&gt;, fail closed. A work package whose owned files
nothing touched on the PR side still refuses &lt;code dir=&quot;auto&quot;&gt;IMPLEMENTATION_MISSING&lt;/code&gt;; read this
acceptance as “the mission’s content landed”, not as a substitute for reviewing the PR’s
own file list.&lt;/p&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pr-body-contract&quot;&gt;PR-body contract&lt;/h2&gt;
&lt;p&gt;Spec Kitty PRs use a fixed body shape; an ad-hoc body (Summary/Changes/Why/…) draws a
squad &lt;strong&gt;MAJOR&lt;/strong&gt; and blocks merge even when the diff is perfect. The shape is the one in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/.github/PULL_REQUEST_TEMPLATE.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;.github/PULL_REQUEST_TEMPLATE.md&lt;/code&gt;&lt;/a&gt;; start from
that template. Exactly five sections, in order:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;## Issue&lt;/code&gt; — must carry a &lt;code dir=&quot;auto&quot;&gt;closes #&amp;#x3C;n&gt;&lt;/code&gt; link. If no tracking issue exists, &lt;strong&gt;file/claim
one first&lt;/strong&gt; (a docs-gap issue counts), name the branch &lt;code dir=&quot;auto&quot;&gt;issue-&amp;#x3C;n&gt;-&amp;#x3C;slug&gt;&lt;/code&gt; (not a bare
&lt;code dir=&quot;auto&quot;&gt;docs/&amp;#x3C;slug&gt;&lt;/code&gt;), and align the PR title to the &lt;code dir=&quot;auto&quot;&gt;[#&amp;#x3C;n&gt;] …&lt;/code&gt; form.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;## Change&lt;/code&gt; — what changed and why.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;## Tests run&lt;/code&gt; — must contain a nested &lt;code dir=&quot;auto&quot;&gt;Self-review:&lt;/code&gt; block, and every recorded command
must be &lt;strong&gt;runnable verbatim&lt;/strong&gt; (full &lt;code dir=&quot;auto&quot;&gt;tests/…&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;docs/…&lt;/code&gt; paths; invoke doc scripts as
&lt;code dir=&quot;auto&quot;&gt;uv run python -m scripts.docs.&amp;#x3C;x&gt;&lt;/code&gt;, never the bare &lt;code dir=&quot;auto&quot;&gt;scripts/docs/&amp;#x3C;x&gt;.py&lt;/code&gt; path, which
fails &lt;code dir=&quot;auto&quot;&gt;ModuleNotFoundError: scripts&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;## Blast radius&lt;/code&gt; — a &lt;code dir=&quot;auto&quot;&gt;Discovery:&lt;/code&gt; line (the git-grep command) plus &lt;code dir=&quot;auto&quot;&gt;Files:&lt;/code&gt; (paths
re-derived from a fresh run of it).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;## Deferred&lt;/code&gt; — anything intentionally left for follow-up.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The shape is defined by the template above; the internal validator
&lt;code dir=&quot;auto&quot;&gt;packs/internal/assets/validate-pr-body.py&lt;/code&gt; (stdlib only; internal pack, never shipped to
consumers) enforces it, and the fleet squad runs it. It checks the five sections in order,
a &lt;code dir=&quot;auto&quot;&gt;closes #&amp;#x3C;n&gt;&lt;/code&gt; line, a &lt;code dir=&quot;auto&quot;&gt;Self-review:&lt;/code&gt; block inside Tests run, runnable test commands, and
&lt;code dir=&quot;auto&quot;&gt;Discovery:&lt;/code&gt; plus &lt;code dir=&quot;auto&quot;&gt;Files:&lt;/code&gt; in Blast radius, and it rejects a body that still carries the
template’s placeholders. Run it before opening, from a file or stdin:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;python packs/internal/assets/validate-pr-body.py body.md&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;gh pr view &amp;#x3C;n&gt; --json body -q .body | python packs/internal/assets/validate-pr-body.py -&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;If you do not have a Spec Kitty source checkout with this internal asset, check the body
against the template manually: keep exactly the five headings above in order; put an
own-line &lt;code dir=&quot;auto&quot;&gt;Closes #&amp;#x3C;n&gt;&lt;/code&gt; in Issue; list runnable commands and their results plus a
&lt;code dir=&quot;auto&quot;&gt;Self-review:&lt;/code&gt; block in Tests run; record the actual &lt;code dir=&quot;auto&quot;&gt;git grep&lt;/code&gt; discovery command and
its matching paths under &lt;code dir=&quot;auto&quot;&gt;Files:&lt;/code&gt; in Blast radius; and remove all template placeholders.&lt;/p&gt;
&lt;p&gt;After the last rebase, prove the &lt;code dir=&quot;auto&quot;&gt;Files:&lt;/code&gt; list against a fresh run of the &lt;code dir=&quot;auto&quot;&gt;Discovery:&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;git grep&lt;/code&gt; at the head you are landing (only a &lt;code dir=&quot;auto&quot;&gt;git grep&lt;/code&gt; command is ever executed):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;python packs/internal/assets/validate-pr-body.py body.md --verify-discovery --expected-head &amp;#x3C;sha&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Exit 0 means valid; exit 1 prints one &lt;code dir=&quot;auto&quot;&gt;section: problem&lt;/code&gt; line per violation; exit 2 is a
usage error. Note the description-length SEO check
(50–180 chars) is &lt;strong&gt;CI-only&lt;/strong&gt; — run &lt;code dir=&quot;auto&quot;&gt;tests/docs/test_docs_seo.py&lt;/code&gt; as part of any docs
blast radius.&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/review-gates/&quot;&gt;Review gates: pre-PR / pre-review checklist&lt;/a&gt; — the
contributor-side hygiene this runbook assumes.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/testing/testing-flakiness/&quot;&gt;Test-flakiness handling policy&lt;/a&gt; — the
never-retry-to-green rule and budget-gate tuning.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/&quot;&gt;Guides index&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
