<?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/manage-issue-tracker/">
  <id>https://docs.spec-kitty.ai/development/how-to/manage-issue-tracker/</id>
  <title>Managing the Issue Tracker</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/manage-issue-tracker/"/>
  <summary>Conventions for the Spec Kitty issue tracker: epics vs meta-trackers, sub-issue parenting, dependencies, triage, the label taxonomy, and the label-driven fleet workflow.</summary>
  <content type="html">&lt;span id=&quot;managing-the-issue-tracker&quot;&gt;&lt;/span&gt;
&lt;p&gt;This guide describes how Spec Kitty structures its GitHub issue tracker so the
work graph stays honest, machine-navigable, and free of the drift that
hand-maintained checklists cause. It is aimed at maintainers and agents doing
tracker hygiene — parenting issues, wiring dependencies, and pruning stale
rollups.&lt;/p&gt;
&lt;p&gt;The rules exist because a misleading work graph is expensive: a real defect
parented under a release rollup is hidden when that rollup is closed, and a
dependency captured only as prose is invisible to every tool that reads the
tracker.&lt;/p&gt;
&lt;h2 id=&quot;functional-epics-versus-meta-trackers&quot;&gt;Functional epics versus meta-trackers&lt;/h2&gt;
&lt;p&gt;The tracker has two distinct kinds of parent issue. Telling them apart is the
first decision in any hygiene pass.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A &lt;strong&gt;functional epic&lt;/strong&gt; is a real domain or slice of work. It owns
&lt;strong&gt;native GitHub sub-issue children&lt;/strong&gt;, carries the &lt;code dir=&quot;auto&quot;&gt;epic&lt;/code&gt; label, and has a
body that describes the work (see &lt;a href=&quot;#epic-bodies-describe-work-not-children&quot;&gt;Epic bodies&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;meta-tracker&lt;/strong&gt; is a convenience rollup — a release go/no-go list, a
stabilization checklist, or a dashboard view. It carries the &lt;code dir=&quot;auto&quot;&gt;meta-tracker&lt;/code&gt;
label, its body is a checklist that &lt;em&gt;references&lt;/em&gt; issues owned elsewhere, and
it has &lt;strong&gt;no native children of its own&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The distinguishing test is native children, not the title.&lt;/strong&gt; An issue titled
&lt;code dir=&quot;auto&quot;&gt;Umbrella: …&lt;/code&gt; that owns native sub-issues is a functional epic; an issue that
holds only a body checklist of items homed under other epics is a
meta-tracker. Judge by the sub-issue graph, never by the name.&lt;/p&gt;
&lt;p&gt;Parent functional issues under functional epics only. Never parent a real
work item under a meta-tracker.&lt;/p&gt;
&lt;h2 id=&quot;parent-and-child-are-native-sub-issue-links&quot;&gt;Parent and child are native sub-issue links&lt;/h2&gt;
&lt;p&gt;Express the parent/child relationship as a &lt;strong&gt;native GitHub sub-issue link&lt;/strong&gt;, not
as a &lt;code dir=&quot;auto&quot;&gt;## Children&lt;/code&gt; checklist in the parent’s body. Body checklists duplicate the
relationship and silently drift out of sync.&lt;/p&gt;
&lt;p&gt;Create a link (REST — &lt;code dir=&quot;auto&quot;&gt;sub_issue_id&lt;/code&gt; is the child’s numeric &lt;strong&gt;database&lt;/strong&gt; id, not
its issue number):&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;CID&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;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:#ECC48D;--1:#3B61B0&quot;&gt;repos/OWNER/REPO/issues/&amp;#x3C;CHILD&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;--jq&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;.id&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;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;--method&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;POST&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;repos/OWNER/REPO/issues/&amp;#x3C;PARENT&gt;/sub_issues&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;-F&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;sub_issue_id=&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;$CID&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;Or via GraphQL (node ids, not numbers):&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;PID&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;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:#ECC48D;--1:#3B61B0&quot;&gt;repos/OWNER/REPO/issues/&amp;#x3C;PARENT&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;--jq&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;.node_id&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:#C5E478;--1:#3B61B0&quot;&gt;CID&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;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:#ECC48D;--1:#3B61B0&quot;&gt;repos/OWNER/REPO/issues/&amp;#x3C;CHILD&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;--jq&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;.node_id&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;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:#ECC48D;--1:#3B61B0&quot;&gt;graphql&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;-f&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;query=&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;mutation($p:ID!,$c:ID!){addSubIssue(input:{issueId:$p,subIssueId:$c}){issue{number}}}&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:#82AAFF;--1:#3B61B0&quot;&gt;-f&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;p=&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;$PID&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;-f&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;c=&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;$CID&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;List a parent’s children with &lt;code dir=&quot;auto&quot;&gt;gh api repos/OWNER/REPO/issues/&amp;#x3C;PARENT&gt;/sub_issues&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Single-parent constraint.&lt;/strong&gt; GitHub allows an issue only one parent; a second
link attempt returns HTTP 422. To &lt;strong&gt;reparent&lt;/strong&gt;, remove the old link first, then
add the new one:&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;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:#ECC48D;--1:#3B61B0&quot;&gt;graphql&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;-f&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;query=&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;mutation($p:ID!,$c:ID!){removeSubIssue(input:{issueId:$p,subIssueId:$c}){issue{number}}}&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:#82AAFF;--1:#3B61B0&quot;&gt;-f&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;p=&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;$OLD_PARENT_NODE&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;-f&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;c=&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;$CHILD_NODE&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:#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:#ECC48D;--1:#3B61B0&quot;&gt;graphql&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;-f&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;query=&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;mutation($p:ID!,$c:ID!){addSubIssue(input:{issueId:$p,subIssueId:$c}){issue{number}}}&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:#82AAFF;--1:#3B61B0&quot;&gt;-f&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;p=&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;$NEW_PARENT_NODE&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;-f&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;c=&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;$CHILD_NODE&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;h2 id=&quot;execution-order-is-blocked_by-not-prose&quot;&gt;Execution order is blocked_by, not prose&lt;/h2&gt;
&lt;p&gt;Encode sequencing as native &lt;code dir=&quot;auto&quot;&gt;blocks&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;blocked_by&lt;/code&gt; dependencies &lt;strong&gt;between
children&lt;/strong&gt;, not as a &lt;code dir=&quot;auto&quot;&gt;#A → #B → #C&lt;/code&gt; sequence in the epic body. An epic body
should carry no ordering prose that a tool cannot read.&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;# REST — issue_id is the BLOCKING issue&apos;s numeric database id&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;--method&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;POST&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;repos/OWNER/REPO/issues/&amp;#x3C;BLOCKED&gt;/dependencies/blocked_by&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;-F&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;issue_id=&amp;#x3C;BLOCKER_DB_ID&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;/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;# GraphQL — issueId is the BLOCKED issue&apos;s node id&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:#ECC48D;--1:#3B61B0&quot;&gt;graphql&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;-f&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;query=&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;mutation($b:ID!,$k:ID!){addBlockedBy(input:{issueId:$b,blockingIssueId:$k}){issue{number}}}&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:#82AAFF;--1:#3B61B0&quot;&gt;-f&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;b=&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;$BLOCKED_NODE&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;-f&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;k=&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;$BLOCKER_NODE&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;For a strangler sequence of children, wire each step &lt;code dir=&quot;auto&quot;&gt;blocked_by&lt;/code&gt; its
predecessor so the ready-to-start item is always unambiguous.&lt;/p&gt;
&lt;h2 id=&quot;epic-bodies-describe-work-not-children&quot;&gt;Epic bodies describe work, not children&lt;/h2&gt;
&lt;p&gt;An epic body is a functional description, not a child enumeration. Every epic
body must convey:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Why&lt;/strong&gt; — the problem or motivation.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;For whom&lt;/strong&gt; — which users or roles benefit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Intended effect&lt;/strong&gt; — the outcome once the epic is done.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Preserve substantive rationale; drop mechanical checklists (the sub-issue graph
already records the children).&lt;/p&gt;
&lt;h2 id=&quot;meta-tracker-lifecycle&quot;&gt;Meta-tracker lifecycle&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Label a meta-tracker &lt;code dir=&quot;auto&quot;&gt;meta-tracker&lt;/code&gt;, never &lt;code dir=&quot;auto&quot;&gt;epic&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Its body checklist is by design. Do &lt;strong&gt;not&lt;/strong&gt; audit a meta-tracker for
“no in-body children” and do &lt;strong&gt;not&lt;/strong&gt; native-link its checklist entries — the
real issues live under their own epics.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Close a meta-tracker once it holds zero native sub-issues.&lt;/strong&gt; Its purpose is
spent when the work it references is tracked under proper epics. Close it with
an audit comment, and explicitly note any residual free-text checklist items
so nothing silently vanishes.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;filing-children-from-an-epic&quot;&gt;Filing children from an epic&lt;/h2&gt;
&lt;p&gt;When you decompose an epic into issues:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Match the epic’s own stated breakdown&lt;/strong&gt; — file exactly the slices the body
names, in the order it names them. Do not invent scope the epic did not
specify; flag anything too vague to file cleanly instead of guessing.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Ground each slice in the real code first.&lt;/strong&gt; If a named slice already shipped,
record that with evidence rather than filing a phantom “to-do” ticket that
misrepresents completed work as pending.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;file-an-issue-in-the-repository-that-owns-the-concern&quot;&gt;File an issue in the repository that owns the concern&lt;/h2&gt;
&lt;p&gt;Three concerns no longer live in this repository. File an issue about any of them
in the repository that owns it, not here:&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Concern&lt;/th&gt;&lt;th&gt;Repository&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Doctrine content: directives, tactics, styleguides, toolguides, procedures, paradigms, agent profiles as content, mission-step prompts and templates, pack manifests and DRG fragments&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty-open-packs&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;The charter service: pack registration and composition, the DRG model and its relations, artifact kinds and schemas, profile resolution and the mission-type API&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty-charter&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;The events domain: the envelope and payload schemas, the &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; reducers and conformance fixtures, the &lt;code dir=&quot;auto&quot;&gt;mission-status&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;mission-write&lt;/code&gt; contracts and the Java read and write services&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty-events&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;File it here when the change lands in this repository. That covers the CLI and
runtime, migrations, &lt;code dir=&quot;auto&quot;&gt;charter.activation&lt;/code&gt;, the in-core Python charter code until it is
retired, and how core consumes the other three: the pins, &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt;, the
&lt;code dir=&quot;auto&quot;&gt;charter.offering.api&lt;/code&gt; seam, the event emitters and the conformance checks.&lt;/p&gt;
&lt;p&gt;When a concern has a half in each, file each half where it lands and link the two.
A bug users hit today in core’s Python stays here, even when the owning repository
will later replace that code. A new capability for the charter service, or a change
to pack content, goes to the owning repository from the start.&lt;/p&gt;
&lt;p&gt;A triage pass that finds a misfiled issue applies the same rule. If the issue can be
moved, recreate it in the owning repository with a &lt;code dir=&quot;auto&quot;&gt;Moved from spec-kitty/spec-kitty#N&lt;/code&gt;
header, its full body and a summary of its comments. Then close the original as
&lt;code dir=&quot;auto&quot;&gt;not_planned&lt;/code&gt; with a link forward. If only half of it belongs elsewhere, split it: open
the other half there, and put a “Scope narrowed” note at the top of the original. The
operator ruled this on 2026-11-12, after the scope-migration sweep of the open core
issues (Op records &lt;code dir=&quot;auto&quot;&gt;01M776T1&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;01M77BZ3&lt;/code&gt;).&lt;/p&gt;
&lt;h2 id=&quot;triaging-issues-type-severity-and-release-blocking-bugs&quot;&gt;Triaging issues: type, severity, and release-blocking bugs&lt;/h2&gt;
&lt;p&gt;Every open issue carries two orthogonal classifications a triage pass must get
right: &lt;strong&gt;what kind of thing it is&lt;/strong&gt; (native type) and &lt;strong&gt;how urgent it is&lt;/strong&gt;
(priority). They are set independently and mean different things. A third,
independent axis — &lt;strong&gt;which code domain it lives in&lt;/strong&gt; — is carried by the
&lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; labels; assign it from
&lt;a href=&quot;#domain-labels-which-code-domain-the-work-routes-to&quot;&gt;Domain labels&lt;/a&gt; rather
than guessing a surface, since that section keys each label to the enforced
Modularity SSOT.&lt;/p&gt;
&lt;h3 id=&quot;native-type-is-the-kind-carrier&quot;&gt;Native type is the kind carrier&lt;/h3&gt;
&lt;p&gt;Set the GitHub &lt;strong&gt;native issue type&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;Task&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt; (the tokens
are case-sensitive: &lt;code dir=&quot;auto&quot;&gt;gh issue edit &amp;#x3C;N&gt; --type Bug&lt;/code&gt;). &lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt; here is GitHub’s
native issue-type name, not Spec Kitty terminology; the domain object is always
a Mission. The type is the &lt;em&gt;sole&lt;/em&gt; kind
carrier; the old &lt;code dir=&quot;auto&quot;&gt;bug&lt;/code&gt; label was retired repo-wide and must not be reintroduced.
A capability request wearing a bug title is a &lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt; (retype it, don’t leave
it as a &lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt;). The &lt;code dir=&quot;auto&quot;&gt;enhancement&lt;/code&gt; label and the whole &lt;code dir=&quot;auto&quot;&gt;type:*&lt;/code&gt; label family are
retired for the same reason; the issue templates set the native type directly.&lt;/p&gt;
&lt;h3 id=&quot;priority-and-what-makes-a-p0&quot;&gt;Priority, and what makes a P0&lt;/h3&gt;
&lt;p&gt;Priority is a label (&lt;code dir=&quot;auto&quot;&gt;priority:P0&lt;/code&gt; … &lt;code dir=&quot;auto&quot;&gt;priority:P3&lt;/code&gt;). &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;priority:P0&lt;/code&gt; on a &lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt;
means a release-blocking defect&lt;/strong&gt; — and, 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;,
that has teeth: &lt;strong&gt;an open P0 bug is expected to red mainline&lt;/strong&gt;, mainline CI is the
authoritative release gate, and &lt;strong&gt;red CI means no release&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;Because a P0 bug halts the release train, calibrate it deliberately. A bug is P0
if it trips any of:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Data/state corruption or loss&lt;/strong&gt; — overwrites recorded results, poisons/drops
events, wrong-authority or split-brain committed writes.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Silent wrong result / false success&lt;/strong&gt; — a command reports success but skips or
loses work (especially damning under the honesty ADR).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Core workflow broken with no workaround&lt;/strong&gt; — cannot implement / review / merge /
accept / commit a mission; a deadlock or hang with no escape hatch.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Blocks release&lt;/strong&gt; directly, or a &lt;strong&gt;security&lt;/strong&gt; exposure (credentials/secrets).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;The escalation test — irreversibility × silence × false-success.&lt;/strong&gt; The four
triggers above share one shape: a defect is P0 when it can &lt;strong&gt;destroy or lie
without telling the operator&lt;/strong&gt;. Weigh three aggravating axes — is the damage
&lt;em&gt;irreversible&lt;/em&gt; (data/state loss, wedged mission with no escape), does it happen
&lt;em&gt;silently&lt;/em&gt; (no error surfaced), and does the tool &lt;em&gt;claim success anyway&lt;/em&gt; (exit 0,
“done”, a fabricated record). A fault that scores on these axes is P0 even when it
feels borderline; a fault that is bounded, loud, and recoverable is not.&lt;/p&gt;
&lt;p&gt;Downgrade below P0 when a clear workaround exists, the fault is edge-case-only,
cosmetic/UX, confined to a dev-assist command, or the exposure is bounded and
sophistication-gated (a narrow race window, an attack needing privileged local
position). &lt;strong&gt;Do not inflate P0&lt;/strong&gt; — crying wolf devalues the red-mainline signal.
But &lt;strong&gt;do not under-call&lt;/strong&gt; a genuine corruption, hang, or false-success:
&lt;strong&gt;when a real destructive/silent/false-success defect is borderline, escalate.
Red main is the safety net, not the failure&lt;/strong&gt; (ADR 2026-07-17-1) — an honestly
red mainline on a genuine P0 is the system working, not breaking. Escalation to
P0 is an operator decision.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The operator-betrayal class is the archetypal P0.&lt;/strong&gt; The most damning defects
this project ships are the ones where &lt;em&gt;Spec Kitty fights its own operator&lt;/em&gt; — the
tool reports success while skipping, losing, or fabricating work: a &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; that
exits 0 repairing nothing, a &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; that prints “cleaned up” while every delete
was refused, a &lt;code dir=&quot;auto&quot;&gt;close&lt;/code&gt; that commits a fabricated completion record, an &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt;
that silently deletes user-authored missions, a &lt;code dir=&quot;auto&quot;&gt;finalize&lt;/code&gt; that wedges the
mission with no escape. These are almost always surfaced by &lt;em&gt;running Spec Kitty on
Spec Kitty&lt;/em&gt; (label them &lt;code dir=&quot;auto&quot;&gt;catfooding&lt;/code&gt;), and under the honesty ADR they are
release-blocking by default: a tool the operator cannot trust to tell the truth
about its own actions is not shippable. Treat operator-betrayal defects as P0
unless a concrete argument downgrades them.&lt;/p&gt;
&lt;p&gt;Priority on a &lt;strong&gt;non-bug&lt;/strong&gt; means something else: a &lt;code dir=&quot;auto&quot;&gt;priority:P0&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;Task&lt;/code&gt;
is the priority of &lt;em&gt;planned work&lt;/em&gt;, not a release-blocking defect — it does not
imply a red mainline.&lt;/p&gt;
&lt;h3 id=&quot;a-p0-bug-should-carry-a-failing-reproduction-test&quot;&gt;A P0 bug should carry a failing reproduction test&lt;/h3&gt;
&lt;p&gt;Per the ADR, when you file or accept a P0 bug, land an &lt;strong&gt;issue-pinned red-first
reproduction test&lt;/strong&gt; so CI honestly reflects the blocker instead of only asserting it.
Mark it &lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro(issue=N)&lt;/code&gt;, reproduce the defect through the
pre-existing entry point, and say in the docstring that it is an intentional red-first P0
reproduction. It must fail because of the product defect, not because of a test error: a
false red corrupts the signal it exists to give.&lt;/p&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;p0_repro&lt;/code&gt; tests run &lt;strong&gt;only&lt;/strong&gt; in the nightly &lt;code dir=&quot;auto&quot;&gt;p0-repro&lt;/code&gt; lane. They never run in a PR’s CI,
so PRs land on green while the nightly, and therefore the release, stays blocked until the
fix lands. The fix PR removes the marker. Do &lt;strong&gt;not&lt;/strong&gt; use &lt;code dir=&quot;auto&quot;&gt;regression&lt;/code&gt; (per-PR guards for
bugs that are already fixed) or &lt;code dir=&quot;auto&quot;&gt;quarantine&lt;/code&gt; (built never to run) for an open P0.
Expensive QA and manual testing wait for green, and maintainers prioritize red recovery.
See the &lt;a href=&quot;/development/reference/red-main-and-release-readiness/#where-the-reproduction-runs-the-nightly-p0-repro-lane&quot;&gt;red-main policy&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;what-good-first-issue-means-here&quot;&gt;What “good first issue” means here&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;good first issue&lt;/code&gt; is &lt;strong&gt;not&lt;/strong&gt; a difficulty or seniority signal — this project’s
contributor base is senior by default. It marks a &lt;strong&gt;good entry point into the
codebase&lt;/strong&gt;: a self-contained issue that teaches a subsystem while carrying &lt;strong&gt;low
customer and blast-radius impact&lt;/strong&gt;, so someone new to the repo can land it
without first absorbing deep cross-cutting context.&lt;/p&gt;
&lt;p&gt;Reach for it when an issue is well-scoped, has a clear deliverable, and touches a
peripheral or tooling surface rather than a load-bearing one. One guardrail: if a
&lt;code dir=&quot;auto&quot;&gt;good first issue&lt;/code&gt; could still alter a &lt;strong&gt;blocking or shared gate&lt;/strong&gt; (or otherwise
carry real blast radius despite being a good entry point), require maintainer
concurrence on the chosen approach &lt;strong&gt;before&lt;/strong&gt; implementation — normal PR review
then covers the rest.&lt;/p&gt;
&lt;h3 id=&quot;running-a-triage-pass-over-a-batch-of-issues&quot;&gt;Running a triage pass over a batch of issues&lt;/h3&gt;
&lt;p&gt;A maintainer pass over a batch of open issues (by default those created in the last
7 days) is run by the &lt;code dir=&quot;auto&quot;&gt;issue-triage-pass&lt;/code&gt; procedure, which the &lt;code dir=&quot;auto&quot;&gt;issue-triage&lt;/code&gt; pack skill
starts. The orchestrator fixes the work list and the code baseline, dispatches triage
subagents that load the &lt;code dir=&quot;auto&quot;&gt;planner-priti&lt;/code&gt; profile, re-checks every issue before each write,
and puts the flagged items to the operator. The rules above are what each subagent
applies. Three points are easy to miss:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Never set &lt;code dir=&quot;auto&quot;&gt;priority:P0&lt;/code&gt; in a pass.&lt;/strong&gt; Name the criterion the issue meets and flag
it; escalation is the operator’s decision.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Leave &lt;code dir=&quot;auto&quot;&gt;status:*&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt; alone, with one exception.&lt;/strong&gt; They are leases
and queue state, set by a human or by contributor tooling (see
&lt;a href=&quot;#issue-workflow-state-labels&quot;&gt;Issue workflow-state labels&lt;/a&gt;). The exception is
&lt;code dir=&quot;auto&quot;&gt;status:triage&lt;/code&gt;: once an issue’s triage decisions are applied, remove it, and add no
other status label in its place (&lt;code dir=&quot;auto&quot;&gt;triage:*&lt;/code&gt; sub-labels stay). A flagged issue keeps
&lt;code dir=&quot;auto&quot;&gt;status:triage&lt;/code&gt; until the operator’s ruling is applied. Report any other status label
that looks stale.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Check liveness against the canonical remote.&lt;/strong&gt; Judge “still exists” or “already
shipped” against &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; of &lt;code dir=&quot;auto&quot;&gt;spec-kitty/spec-kitty&lt;/code&gt;, fetched now, not a fork’s
&lt;code dir=&quot;auto&quot;&gt;origin/main&lt;/code&gt;, which can lag far behind.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;milestones-and-release-cycles&quot;&gt;Milestones and release cycles&lt;/h2&gt;
&lt;p&gt;Milestones carry release scope; labels carry kind, priority, and domain. The
active cycle is &lt;strong&gt;4.0.0&lt;/strong&gt;, currently at the release-candidate stage on &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;.
The &lt;a href=&quot;/plans/4-0-0-milestone-roadmap/&quot;&gt;4.0.0 milestone roadmap&lt;/a&gt; is the
authority for what each milestone means. In short:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;4.0.0 release scope&lt;/strong&gt; — the GA gate: issues that must close before a non-rc
&lt;code dir=&quot;auto&quot;&gt;4.0.0&lt;/code&gt; ships. Put an issue here only if it truly blocks GA.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;CLI 4.x stable&lt;/strong&gt; — stable 4.x work after the 4.0.0 launch. Post-4.0.0
deferrals go here.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;4.x Work&lt;/strong&gt; — the former &lt;code dir=&quot;auto&quot;&gt;4.0.0&lt;/code&gt; milestone; now hosted-collaboration and
product work beyond the stabilization release. Being on it does not make an
issue a GA blocker.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The 3.x milestones are closed: 3.2.7 was the last 3.x release, and the 3.3.x
milestone was retired on 2026-08-23 without shipping. An issue whose text says
“deferred to 3.3.x” needs re-triage onto one of the milestones above; do not
reopen or reuse the 3.x milestones.&lt;/p&gt;
&lt;h2 id=&quot;label-taxonomy&quot;&gt;Label taxonomy&lt;/h2&gt;
&lt;p&gt;Two orthogonal axes carry the load and are documented above: the &lt;strong&gt;native type&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;Feature&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;Task&lt;/code&gt; — the sole kind carrier) and &lt;strong&gt;priority&lt;/strong&gt;
(&lt;code dir=&quot;auto&quot;&gt;priority:P0&lt;/code&gt;…&lt;code dir=&quot;auto&quot;&gt;priority:P3&lt;/code&gt;). Labels never encode kind. The &lt;code dir=&quot;auto&quot;&gt;bug&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;enhancement&lt;/code&gt; labels and the whole &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;type:*&lt;/code&gt; label family&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;type:bug&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;type:feature&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;type:chore&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;type:fix&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;type:finding&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;type:flake&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;type:thesis&lt;/code&gt;) duplicated the native issue type as a parallel, drift-prone kind
carrier and are &lt;strong&gt;retired&lt;/strong&gt;: the native GitHub type is the single canonical
authority for kind. These labels were deleted from the repository on 2026-10-19;
if one reappears, strip it and set the native type. The former &lt;code dir=&quot;auto&quot;&gt;type:decision&lt;/code&gt;
label is now &lt;code dir=&quot;auto&quot;&gt;triage:needs-decision&lt;/code&gt; (see
&lt;a href=&quot;#triage-state-labels--transient-hygiene-state-not-classification&quot;&gt;Triage-state labels&lt;/a&gt;).
Beyond type and
priority, labels fall into the families below. Apply as many as genuinely apply; a &lt;code dir=&quot;auto&quot;&gt;catfooding&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;reliability&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt; at
&lt;code dir=&quot;auto&quot;&gt;priority:P2&lt;/code&gt; is a normal, well-triaged issue.&lt;/p&gt;
&lt;h3 id=&quot;classification-labels--what-kind-of-work-it-is&quot;&gt;Classification labels — what &lt;em&gt;kind of work&lt;/em&gt; it is&lt;/h3&gt;
&lt;p&gt;These describe the nature of the work independently of the subsystem. They are
orthogonal to native type (a &lt;code dir=&quot;auto&quot;&gt;catfooding&lt;/code&gt; issue is still a Bug, Feature, or Task).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;catfooding&lt;/code&gt; — &lt;strong&gt;Doctrine Catfooding&lt;/strong&gt;: dogfooding Spec Kitty’s own
quality/doctrine practices. Applied to defects and frictions surfaced by
&lt;em&gt;running Spec Kitty on Spec Kitty&lt;/em&gt; — a live mission session that exercises the
specify → plan → tasks → implement → review → merge loop and reports where the
tool fought its own operator. This is the dominant classifier for the
post-convergence dogfooding backlog; expect clusters of &lt;code dir=&quot;auto&quot;&gt;catfooding&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;workflow&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;git&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;usability&lt;/code&gt; issues that circle a single root cause.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tidy-up&lt;/code&gt; — Campsite / declutter / degodding cleanup surfaced &lt;em&gt;during other
work&lt;/em&gt; (the boy-scout residue a mission couldn’t fold in-line). The former
&lt;code dir=&quot;auto&quot;&gt;cleanup&lt;/code&gt; label was merged into it.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tech-debt&lt;/code&gt; — Accumulated lint, type-checking, static-analysis, and
code-quality debt.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;design-spike&lt;/code&gt; — Foundational design work.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;research&lt;/code&gt; — Research / experiment validation work.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;domain-labels--which-code-domain-the-work-routes-to&quot;&gt;Domain labels — &lt;em&gt;which code domain&lt;/em&gt; the work routes to&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; labels route an issue to the &lt;strong&gt;code domain&lt;/strong&gt; it lives in. The domain
set is keyed to the &lt;strong&gt;Modularity SSOT&lt;/strong&gt; — the enforced pair CI actually defends,
not this prose:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Module inventory&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;[tool.hatch.build.targets.wheel].packages&lt;/code&gt;, guarded by
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_pyproject_shape.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Import direction&lt;/strong&gt; — the &lt;code dir=&quot;auto&quot;&gt;landscape&lt;/code&gt; fixture in
&lt;code dir=&quot;auto&quot;&gt;tests/architectural/conftest.py&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_layer_rules.py&lt;/code&gt;,
whose enforced chain is
&lt;code dir=&quot;auto&quot;&gt;kernel &amp;#x3C;- charter &amp;#x3C;- {glossary, runtime, mission_runtime} &amp;#x3C;- specify_cli&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Every prose module map — this section,
&lt;a href=&quot;/architecture/00_landscape/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/architecture/00_landscape/README.md&lt;/code&gt;&lt;/a&gt;,
&lt;code dir=&quot;auto&quot;&gt;docs/architecture/04_implementation_mapping&lt;/code&gt; — is a &lt;strong&gt;derived view&lt;/strong&gt;; on any
conflict the enforced pair wins. Because the top &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; module is large, a
few &lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; labels route to its high-traffic sub-packages rather than to the
whole application layer.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Selection rule.&lt;/strong&gt; Pick the &lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; whose code the fix will actually edit;
apply every domain that genuinely applies (a change spanning modules carries one
label per surface it really touches). A &lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; answers &lt;em&gt;which module&lt;/em&gt;,
independently of native type, priority, and the cross-cutting concern labels
below.&lt;/p&gt;









































































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Label&lt;/th&gt;&lt;th&gt;Code domain (SSOT module / sub-package)&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:kernel&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/&lt;/code&gt; — zero-dependency foundation primitives (root layer)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:charter&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/&lt;/code&gt; — governance authority; &lt;strong&gt;includes the former doctrine system&lt;/strong&gt; now absorbed at &lt;code dir=&quot;auto&quot;&gt;src/charter/offering/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:glossary&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/glossary/&lt;/code&gt; — terminology / semantic-integrity pipeline + DRG glossary bridge&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:runtime&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/_internal_runtime/&lt;/code&gt; — canonical mission control loop&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:mission-runtime&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/&lt;/code&gt; — artifact-placement seam (PlacementSeam, resolver port, identity, lifecycle_phase)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:cli&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/&lt;/code&gt; — control-plane / CLI command surface&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:invocation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/invocation/&lt;/code&gt; — dispatch &amp;#x26; profile-invocation routing (Op lifecycle)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:decisions&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/decisions/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;cli/commands/decision.py&lt;/code&gt; — Decision Moment flow, models, emit&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:status&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;lanes/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;coordination/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;workspace/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;state/&lt;/code&gt; — status event-log &amp;#x26; lane state machine; &lt;code dir=&quot;auto&quot;&gt;state/&lt;/code&gt; is the project-scoped state-surface contract and &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; state-root checks&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:consolidation&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/&lt;/code&gt; — lane consolidation, retention, preflight (formerly &lt;code dir=&quot;auto&quot;&gt;domain:merge&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:skills&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/skills/&lt;/code&gt; — command/skill rendering, install, and the command-skills manifest&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:upgrade&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/upgrade/&lt;/code&gt; (incl. &lt;code dir=&quot;auto&quot;&gt;upgrade/migrations/&lt;/code&gt;) + &lt;code dir=&quot;auto&quot;&gt;cli/commands/upgrade.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;spec-kitty upgrade&lt;/code&gt;: version detection, migration registry/runner, redeploying generated commands and skills&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:review&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/review/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;cli/commands/review/&lt;/code&gt; — WP review cycle, verdicts, arbiter, the pre-review transition gate (&lt;code dir=&quot;auto&quot;&gt;gate_registry&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pre_review_gate&lt;/code&gt;), and the &lt;code dir=&quot;auto&quot;&gt;spec-kitty review&lt;/code&gt; mission-review gates&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:acceptance&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/acceptance/&lt;/code&gt; — the &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; gate: acceptance matrix, verify, &lt;code dir=&quot;auto&quot;&gt;summary_core&lt;/code&gt; path conventions&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:orchestrator&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/orchestrator_api/&lt;/code&gt; — the &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; external machine contract (JSON envelope + subcommands), documented in &lt;code dir=&quot;auto&quot;&gt;docs/api/orchestrator-api.md&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:contracts&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/contracts/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;docs/contracts/&lt;/code&gt; — payload / handoff-packet contract registry&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:tracker&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/tracker/&lt;/code&gt; — tracker provider integrations &amp;#x26; connectors (&lt;code dir=&quot;auto&quot;&gt;spec_kitty_tracker&lt;/code&gt; consumer)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:docs&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;scripts/docs/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/docs/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;cli/commands/docs.py&lt;/code&gt; — documentation content, docs build/freshness tooling, and the &lt;code dir=&quot;auto&quot;&gt;docs query&lt;/code&gt; retrieval index&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:ci&lt;/code&gt;&lt;/td&gt;&lt;td&gt;GitHub Actions workflows (&lt;code dir=&quot;auto&quot;&gt;.github/workflows/&lt;/code&gt;) + &lt;code dir=&quot;auto&quot;&gt;scripts/ci/&lt;/code&gt; — pipeline, gate selection, coverage aggregation&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:onboarding&lt;/code&gt;&lt;/td&gt;&lt;td&gt;first-run setup spanning modules (init, charter, remote, first mission)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:git&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/git/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;src/kernel/git/&lt;/code&gt; — git operations, worktree / topology helpers&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:agent-profiles&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/agent_profiles/&lt;/code&gt; + profile loading in &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:schema-versioning&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/schemas/&lt;/code&gt; — event / payload schema versioning and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; consumption&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;domain:status-api&lt;/code&gt;&lt;/td&gt;&lt;td&gt;the Mission Status Read/Write API service (in spec-kitty-events &lt;code dir=&quot;auto&quot;&gt;service/&lt;/code&gt; since #6915; core pins it in &lt;code dir=&quot;auto&quot;&gt;pins/read-service.source.yaml&lt;/code&gt;), its contract and its consumers (successor of the removed dashboard, #5530; formerly &lt;code dir=&quot;auto&quot;&gt;domain:dashboard&lt;/code&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;domain:ci&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;domain:docs&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;domain:onboarding&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;domain:status-api&lt;/code&gt; name a
&lt;em&gt;workflow surface&lt;/em&gt; or service outside the Python Modularity SSOT rather than a
single package. They are still domain labels because they
answer &lt;em&gt;where the work lives&lt;/em&gt; for routing — unlike the concern labels below,
which name a quality/experience axis that can attach to any domain.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3 id=&quot;legacy-labels--history-only&quot;&gt;Legacy labels — history only&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;legacy:sync&lt;/code&gt; (the local sync transport, deleted in The Convergence, ADR
&lt;a href=&quot;/adr/3.x/2026-09-06-1-convergence-retirement-and-client-repo-inversion/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;2026-09-06-1-convergence-retirement-and-client-repo-inversion&lt;/code&gt;&lt;/a&gt;)
and &lt;code dir=&quot;auto&quot;&gt;legacy:hosted&lt;/code&gt; (the hosted Team Kitty clients &lt;code dir=&quot;auto&quot;&gt;saas_client/&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;zeitgeist_client/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;auth/&lt;/code&gt;, removed in #6164; formerly &lt;code dir=&quot;auto&quot;&gt;domain:hosted&lt;/code&gt;) mark
closed issues for history. Never apply them; re-home any live issue to the
&lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; label whose code the fix edits. The earlier renames of the
non-namespaced labels (&lt;code dir=&quot;auto&quot;&gt;dashboard&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;saas&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agent-profiles&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;schema-versioning&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;git&lt;/code&gt;) are complete. A &lt;code dir=&quot;auto&quot;&gt;legacy:*&lt;/code&gt; label exists only for a
retired &lt;em&gt;code area&lt;/em&gt;; retired &lt;em&gt;process&lt;/em&gt; labels are deleted outright.&lt;/p&gt;
&lt;h3 id=&quot;cross-cutting-concern-labels--what-qualityexperience-axis-not-a-code-domain&quot;&gt;Cross-cutting concern labels — &lt;em&gt;what quality/experience axis&lt;/em&gt;, not a code domain&lt;/h3&gt;
&lt;p&gt;These name a concern that spans modules; they are &lt;strong&gt;not&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; labels and
do not route to one package. Apply them alongside a &lt;code dir=&quot;auto&quot;&gt;domain:*&lt;/code&gt; label.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;reliability&lt;/code&gt; — Runtime reliability, resiliency, observability, incident
prevention.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;usability&lt;/code&gt; — Ergonomics of any operator-facing surface: messages, flags,
output, defaults.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;workflow&lt;/code&gt; — The mission loop itself (specify → plan → tasks → implement →
review → consolidate) behaves wrongly or awkwardly.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;windows&lt;/code&gt; — Windows-specific issues (a platform axis, not a module).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;triage-state-labels--transient-hygiene-state-not-classification&quot;&gt;Triage-state labels — transient hygiene state, not classification&lt;/h3&gt;
&lt;p&gt;These record &lt;em&gt;where an issue sits in triage&lt;/em&gt;. Remove them once resolved; they are
working state, not a permanent property.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:maybe-duplicate&lt;/code&gt; — Suspected duplicate pending confirmation (as opposed
to the confirmed &lt;code dir=&quot;auto&quot;&gt;duplicate&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:needs-revision&lt;/code&gt; — Scope/spec needs rework before action.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:stale&lt;/code&gt; — Reproduce and close if no longer valid.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:repro-needed&lt;/code&gt; — Reported against behavior that may already be fixed;
needs live re-reproduction before implementing.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:needs-investigation&lt;/code&gt; — Root cause is not yet adjudicated. The defect is
real (often a confirmed red), but which layer owns it is unknown — e.g. a red
test that could be a stale fixture/seed &lt;em&gt;or&lt;/em&gt; a genuine product bug. Blocks final
homing (parent/priority) until an investigation or debugger pass resolves the
root-cause axis; remove it once the cause is known.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;triage:needs-decision&lt;/code&gt; — A human (operator or maintainer) must make a call
before anyone implements; the body states the options. Formerly &lt;code dir=&quot;auto&quot;&gt;type:decision&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Apply at most one &lt;code dir=&quot;auto&quot;&gt;triage:*&lt;/code&gt; label per triage cycle.&lt;/p&gt;
&lt;h3 id=&quot;provenance-labels--who-surfaced-it&quot;&gt;Provenance labels — who surfaced it&lt;/h3&gt;
&lt;p&gt;These record where an issue came from. Provenance is orthogonal to type,
priority and domain.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;from:ci&lt;/code&gt; — Filed by CI automation (&lt;code dir=&quot;auto&quot;&gt;scripts/ci/nightly_escalation.py&lt;/code&gt;). Code
writes and searches for it; never remove it by hand.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;from:qa&lt;/code&gt; — Found by a human QA tester.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;from:dev&lt;/code&gt; — Found during development.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;from:squad&lt;/code&gt; — An adversarial-squad finding (the &lt;code dir=&quot;auto&quot;&gt;adversarial-squad&lt;/code&gt; skill).&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;pr-workflow-labels--for-pull-requests-not-issues&quot;&gt;PR-workflow labels — for pull requests, not issues&lt;/h3&gt;
&lt;p&gt;These live on pull requests, not issues.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ready-for-squad&lt;/code&gt; — the implementer has run the required tests and self-review;
the PR is finished and independently testable. Do &lt;strong&gt;not&lt;/strong&gt; apply it to a
still-draft scope or to work whose tests have not run. (While the
&lt;a href=&quot;/development/agent-fleet/&quot;&gt;SkyKitty agent fleet&lt;/a&gt; was active this label also handed the
PR to the fleet; the fleet is switched off.)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:p0-repro&lt;/code&gt; — the PR lands the red-first reproduction test for a confirmed open
P0 &lt;code dir=&quot;auto&quot;&gt;Bug&lt;/code&gt;. Reference the issue with &lt;code dir=&quot;auto&quot;&gt;Refs #&amp;#x3C;n&gt;&lt;/code&gt;, not &lt;code dir=&quot;auto&quot;&gt;Closes&lt;/code&gt;, and mark the test
&lt;code dir=&quot;auto&quot;&gt;@pytest.mark.p0_repro(issue=&amp;#x3C;n&gt;)&lt;/code&gt; (see
&lt;a href=&quot;#a-p0-bug-should-carry-a-failing-reproduction-test&quot;&gt;A P0 bug should carry a failing reproduction test&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:needs-refresh&lt;/code&gt; — PR branch drifted from &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;; rebase/refresh before review
or merge.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:needs-revision&lt;/code&gt; — PR has unresolved review findings that must be addressed
before it can merge.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:kept-for-reference&lt;/code&gt; — Kept open for reference/history; not intended to merge
as-is.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:deferred&lt;/code&gt; — Held under a declared freeze; the label-gated CI jobs
(&lt;code dir=&quot;auto&quot;&gt;ci-windows.yml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;check-spec-kitty-events-alignment.yml&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;release-readiness.yml&lt;/code&gt;) are skipped until it is removed.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:skip-ci&lt;/code&gt; — Intentionally skip CI for this PR (docs / manual review only).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pr:pause-ci&lt;/code&gt; — Pause CI and block merge until the label is removed; see
&lt;a href=&quot;/development/how-to/pr-landing/#pausing-a-prs-ci-prpause-ci&quot;&gt;Pausing a PR’s CI&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;lifecycle--community-labels&quot;&gt;Lifecycle &amp;#x26; community labels&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;deferred&lt;/code&gt; — Work paused pending an activation trigger.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;feedback-welcome&lt;/code&gt; — Community feedback &amp;#x26; brainstorming welcome; comment
ideas/objections, no code needed.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;good first issue&lt;/code&gt; — a good &lt;em&gt;entry point&lt;/em&gt; (see
&lt;a href=&quot;#what-good-first-issue-means-here&quot;&gt;What “good first issue” means here&lt;/a&gt;); not a
difficulty signal.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;release&lt;/code&gt; — Release engineering: tagging, publishing, release-pipeline
integrity. Release and launch &lt;em&gt;scope&lt;/em&gt; lives in milestones, not labels.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;duplicate&lt;/code&gt; — A confirmed duplicate; pair it with the native “Close as
duplicate”. &lt;code dir=&quot;auto&quot;&gt;invalid&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;wontfix&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;question&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;help wanted&lt;/code&gt; are retired:
use the native close reason “not planned”, or a &lt;code dir=&quot;auto&quot;&gt;triage:*&lt;/code&gt; label.&lt;/li&gt;
&lt;li&gt;Docs work is routed by &lt;code dir=&quot;auto&quot;&gt;domain:docs&lt;/code&gt; (the former &lt;code dir=&quot;auto&quot;&gt;documentation&lt;/code&gt; label was
merged into it); doctrine prose is routed by &lt;code dir=&quot;auto&quot;&gt;domain:charter&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;grouping-labels-documented-above&quot;&gt;Grouping labels (documented above)&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;epic&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;meta-tracker&lt;/code&gt; are covered in
&lt;a href=&quot;#functional-epics-versus-meta-trackers&quot;&gt;Functional epics versus meta-trackers&lt;/a&gt; —
they are not free-floating classification labels and carry structural obligations
(native children vs. a body checklist).&lt;/p&gt;
&lt;h2 id=&quot;issue-workflow-state-labels&quot;&gt;Issue workflow-state labels&lt;/h2&gt;
&lt;p&gt;The issue-side &lt;code dir=&quot;auto&quot;&gt;status:*&lt;/code&gt; labels and &lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt; are human workflow state:&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Label&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:triage&lt;/code&gt;&lt;/td&gt;&lt;td&gt;New, untriaged work&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Triaged, de-duplicated, and resolvable without a pending decision; ready to pick up&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Someone is actively working the issue. A lease: valid only with a live claim comment naming who is working it. Remove it when you stop&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:blocked&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Blocked, with a &lt;strong&gt;Depends on:&lt;/strong&gt; #&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;n&gt;&lt;/code&gt; line naming the gating issue&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A human contributor owns the issue or its linked PR. Pair it with &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt; when you begin&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Contributor tooling may also set these labels; treat a label it set like one a
person set.&lt;/p&gt;
&lt;h2 id=&quot;label-driven-fleet-workflow&quot;&gt;Label-driven fleet workflow&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Status: the SkyKitty fleet is switched off&lt;/strong&gt; (the &lt;code dir=&quot;auto&quot;&gt;CI Fleet Verdict&lt;/code&gt; workflow
is disabled; last run 2026-09-26). The issue-side &lt;code dir=&quot;auto&quot;&gt;status:*&lt;/code&gt; labels and
&lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt; stay in use as human workflow state (see
&lt;a href=&quot;#issue-workflow-state-labels&quot;&gt;Issue workflow-state labels&lt;/a&gt;). The PR-lane
labels (&lt;code dir=&quot;auto&quot;&gt;squad:*&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;needs:implementer&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ci:green&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ci:red&lt;/code&gt;) were deleted on
2026-10-19 and would be recreated if the fleet is reactivated. The rest of this
section is historical: it records how the fleet consumed the labels while active.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The &lt;a href=&quot;/development/agent-fleet/&quot;&gt;SkyKitty agent fleet&lt;/a&gt; and its sibling programme repos run on a
&lt;strong&gt;label-driven queue&lt;/strong&gt;: GitHub labels are the &lt;em&gt;only&lt;/em&gt; admission control. Agents and humans
move work by changing labels, never by out-of-band assignment. This section documents the
queue that consumes the labels catalogued above. Source of truth: the planning repo’s
&lt;code dir=&quot;auto&quot;&gt;agents/dispatcher.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agents/groom.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agents/merge.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;agents/review.md&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;PROGRAM.md&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The fleet scripts named below (&lt;code dir=&quot;auto&quot;&gt;bin/unblock.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;bin/take-next-ticket.sh&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;bin/dispatch.sh&lt;/code&gt;) live in the private &lt;code dir=&quot;auto&quot;&gt;EXPERIMENTAL-spec-kitty-planning&lt;/code&gt; repository,
not in this Spec Kitty checkout. They describe fleet behavior; contributors do not
need to run them to manage an issue.&lt;/p&gt;
&lt;h3 id=&quot;the-status-lifecycle-issues&quot;&gt;The &lt;code dir=&quot;auto&quot;&gt;status:*&lt;/code&gt; lifecycle (issues)&lt;/h3&gt;
&lt;p&gt;This is the fleet’s admission lifecycle, distinct from the transient &lt;code dir=&quot;auto&quot;&gt;triage:*&lt;/code&gt; hygiene
sub-states above (which flag &lt;em&gt;why&lt;/em&gt; an issue sits in triage, not &lt;em&gt;where&lt;/em&gt; it is in the queue).&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Label&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;th&gt;Who sets it&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:triage&lt;/code&gt;&lt;/td&gt;&lt;td&gt;New/untriaged work. The groom agent’s queue.&lt;/td&gt;&lt;td&gt;Filing agents (&lt;code dir=&quot;auto&quot;&gt;from:review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;from:squad&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;from:ci&lt;/code&gt;, …) always file into triage&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Valid, de-duplicated, resolvable without a reserved decision. &lt;strong&gt;The fleet’s admission queue.&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The groom agent promotes triage → ready. Review-agent findings are promoted by the controller, never by the review agent itself&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;&lt;/td&gt;&lt;td&gt;An implementer is actively working this issue. &lt;strong&gt;Lease — valid only with a live claim comment naming the harness/model or dispatcher VM.&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;The dispatcher sets and reaps fleet claims. A human-driven contributor must add both &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt; when beginning work, then comment &lt;code dir=&quot;auto&quot;&gt;claimed by &amp;#x3C;harness&gt;/&amp;#x3C;model&gt; on &amp;#x3C;machine&gt;&lt;/code&gt;. Never add a bare claim when nobody is working the issue: the dispatcher treats the label as occupied capacity&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;status:blocked&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Genuinely blocked, with a &lt;strong&gt;Depends on:&lt;/strong&gt; #&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C;n&gt;&lt;/code&gt; line naming the concrete gating issue. &lt;code dir=&quot;auto&quot;&gt;bin/unblock.py&lt;/code&gt; flips it back to &lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt; automatically once all dependencies close.&lt;/td&gt;&lt;td&gt;Groom/controller&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;taken-by-human&lt;/code&gt;&lt;/td&gt;&lt;td&gt;A human contributor (not a fleet VM) owns the linked PR. &lt;strong&gt;The only label that keeps the fleet’s PR-routed fix and recovery lanes off human-driven work:&lt;/strong&gt; those lanes select on the PR’s own labels and never see the linked issue’s &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;, so this — not &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt; — is what holds a fleet implementer VM off your PR (&lt;code dir=&quot;auto&quot;&gt;PROGRAM.md&lt;/code&gt; §13). (Initial admission is separate: the dispatcher already skips issues that carry &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;.) Pair it with &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt; on the issue when you begin.&lt;/td&gt;&lt;td&gt;The human contributor; &lt;code dir=&quot;auto&quot;&gt;bin/take-next-ticket.sh&lt;/code&gt; sets it automatically for fleet-assisted human claims&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Issues with no &lt;code dir=&quot;auto&quot;&gt;status:*&lt;/code&gt; label &lt;strong&gt;and&lt;/strong&gt; an open linked PR (a real &lt;code dir=&quot;auto&quot;&gt;closes #&lt;/code&gt; relationship)
are &lt;strong&gt;mid-negotiation&lt;/strong&gt;, not unowned — the groom skips them deliberately.&lt;/p&gt;
&lt;h3 id=&quot;admission-from-label-to-vm&quot;&gt;Admission: from label to VM&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;The dispatcher (&lt;code dir=&quot;auto&quot;&gt;bin/dispatch.sh&lt;/code&gt;, deterministic, not an LLM) sweeps continuously. Each
sweep lists open issues with &lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt; and &lt;strong&gt;no&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;, ordered by
priority &lt;code dir=&quot;auto&quot;&gt;P0..P3&lt;/code&gt;, then repo order (&lt;code dir=&quot;auto&quot;&gt;PROGRAM.md&lt;/code&gt; §2), then issue number.&lt;/li&gt;
&lt;li&gt;It skips issues labelled &lt;code dir=&quot;auto&quot;&gt;status:blocked&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;epic&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;triage:needs-decision&lt;/code&gt; (formerly
&lt;code dir=&quot;auto&quot;&gt;type:decision&lt;/code&gt;; a reactivated dispatcher must match the new name) — a decision issue
is never autonomous implementation work, even at &lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt;; it waits on a resolving
comment (&lt;code dir=&quot;auto&quot;&gt;docs/DECISION-ISSUES.md&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;For each issue up to free implementer capacity, the dispatcher claims it: adds
&lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;, comments &lt;code dir=&quot;auto&quot;&gt;claimed by dispatcher → sk-impl-&amp;#x3C;repo&gt;-&amp;#x3C;n&gt;&lt;/code&gt;, and boots a
one-shot implementer VM.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reaping:&lt;/strong&gt; when an implementer VM exits with no linked PR, the dispatcher posts the last
40 log lines as &lt;code dir=&quot;auto&quot;&gt;[dispatcher] implementer exited without a PR&lt;/code&gt;, removes &lt;code dir=&quot;auto&quot;&gt;status:claimed&lt;/code&gt;,
and destroys the VM — the issue returns to the &lt;code dir=&quot;auto&quot;&gt;status:ready&lt;/code&gt; queue and is re-claimed on a
later sweep. A VM older than 6 hours with no PR is treated the same.&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;pr-lane-labels-review-and-landing-historical-labels-deleted&quot;&gt;PR-lane labels (review and landing; historical, labels deleted)&lt;/h3&gt;
&lt;p&gt;PRs moved through their own label set, driven by the same dispatcher (see also the
&lt;code dir=&quot;auto&quot;&gt;ready-for-squad&lt;/code&gt; handshake under &lt;a href=&quot;#pr-workflow-labels--for-pull-requests-not-issues&quot;&gt;PR-workflow labels&lt;/a&gt;):&lt;/p&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Label&lt;/th&gt;&lt;th&gt;Meaning&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ready-for-squad&lt;/code&gt;&lt;/td&gt;&lt;td&gt;PR is ready for adversarial review; dispatcher boots a squad VM (one iteration)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;squad:running&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Squad VM active (lease; stale-claim recovery requires confirming the VM is actually dead, never elapsed time alone)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;squad:passed&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;squad:majors&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Squad verdict. Two &lt;code dir=&quot;auto&quot;&gt;squad:majors&lt;/code&gt; rounds is the cap — the merge agent then decides merge-with-findings or sends it back; never a third squad&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;squad:exhausted&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Two verdicts already posted (or the merge agent ruled out a further pass); merge proceeds on &lt;code dir=&quot;auto&quot;&gt;[ci]&lt;/code&gt; + controller evidence&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;ci:green&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;ci:red&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Best-effort label mirror of the latest exact-head &lt;code dir=&quot;auto&quot;&gt;[ci]&lt;/code&gt; comment. The comment is authoritative; the label is never a gate on its own&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;needs:implementer&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Any fix/rebase request that expects a new push. &lt;strong&gt;Mandatory on every such request&lt;/strong&gt; — the dispatcher dispatches fix-round VMs when this label or &lt;code dir=&quot;auto&quot;&gt;squad:majors&lt;/code&gt; admits the PR to the fix lane; a request comment carrying neither is never seen&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&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/agent-fleet/&quot;&gt;The SkyKitty agent fleet&lt;/a&gt; — the fleet that acts on this repo, its
roles, and the &lt;code dir=&quot;auto&quot;&gt;ready-for-squad&lt;/code&gt; handshake these labels feed.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/contributing/&quot;&gt;Contributing to Spec Kitty&lt;/a&gt; — pull-request and maintainer workflow.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/missions/keep-main-clean/&quot;&gt;Keep main clean&lt;/a&gt; — branch and merge discipline.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/pr-landing/&quot;&gt;PR landing&lt;/a&gt; — the fork-PR landing runbook, incl. red classification.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/reference/red-main-and-release-readiness/&quot;&gt;Red main and release readiness&lt;/a&gt; — what a red main means and the release gate.&lt;/li&gt;
&lt;li&gt;&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 — Red main is honest signal; CI is the release authority&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
