<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-08-15-1-handoff-packet-intake-contract/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-15-1-handoff-packet-intake-contract/</id>
  <title>ADR: Own a Tool-Agnostic, Versioned, Optional Handoff-Packet Intake Contract</title>
  <updated>2026-08-15T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-08-15-1-handoff-packet-intake-contract/"/>
  <summary>Ratifies handoff-packet v1: an additive, version-gated frontmatter overlay that seeds spec-kitty intake with stable FR/AC ids from upstream tools, degrading to prose when absent.</summary>
  <content type="html">&lt;h2 id=&quot;own-a-tool-agnostic-versioned-optional-handoff-packet-intake-contract&quot;&gt;Own a Tool-Agnostic, Versioned, Optional Handoff-Packet Intake Contract&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-15-1-handoff-packet-intake-contract.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-15&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Maintainer&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/3379&quot;&gt;PR #3379&lt;/a&gt;&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty intake&lt;/code&gt; today only accepts unstructured Markdown. When a brief was
authored (or exported) by an upstream requirements tool, &lt;code dir=&quot;auto&quot;&gt;/spec-kitty.specify&lt;/code&gt;
re-mints FR and AC ids from prose and drops the producer’s native identity —
so a ticket, story, or use-case id that already existed upstream has no
traceable link to the Spec Kitty artifact born from it. Upstream requirements
tools generally do have stable ids worth preserving across that passage.&lt;/p&gt;
&lt;p&gt;Spec Kitty should be able to accept a structured seed from any such tool
without knowing anything about that tool specifically — no ticket-key shape,
no story-id convention, no producer-specific vocabulary baked into the
schema. This ADR ratifies that PR #3379’s answer to that problem is a
contract Spec Kitty owns and commits to, not a one-off parsing convenience.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Preserve producer-native FR/AC identity across intake instead of re-minting it.&lt;/li&gt;
&lt;li&gt;Never require a specific upstream tool, and never let any tool’s vocabulary
leak into the schema.&lt;/li&gt;
&lt;li&gt;Zero risk to the existing, already-working prose-intake path.&lt;/li&gt;
&lt;li&gt;Producer-controlled strings are filesystem input from an untrusted source.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Own a &lt;strong&gt;tool-agnostic, optional, versioned&lt;/strong&gt; intake overlay — the handoff-packet
contract at &lt;a href=&quot;/contracts/handoff-packet-v1/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/contracts/handoff-packet-v1.md&lt;/code&gt;&lt;/a&gt; — bound by three invariants:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Additive; degrades to prose.&lt;/strong&gt; A packet-less or malformed brief behaves
exactly as today’s intake. &lt;code dir=&quot;auto&quot;&gt;spec-kitty intake&lt;/code&gt; never fails because the
overlay is absent or invalid — a malformed packet still ingests the file
as a prose brief; only the structured overlay is dropped.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Version-gated.&lt;/strong&gt; The overlay activates only on &lt;code dir=&quot;auto&quot;&gt;handoff_packet: 1&lt;/code&gt;.
Unknown or future versions degrade to prose. A v2, if one is ever needed,
ships as a parallel, additive step alongside v1 rather than replacing it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;All producer strings are untrusted.&lt;/strong&gt; Provenance scalars are sanitised
(&lt;code dir=&quot;auto&quot;&gt;escape_for_comment&lt;/code&gt;, ASCII control-character stripping, a 256-byte clip)
before they land in &lt;code dir=&quot;auto&quot;&gt;.kittify/brief-source.yaml&lt;/code&gt; or any HTML/Markdown
comment. The brief’s SHA-256 hash stays computed over the raw file, not
the parsed overlay.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The existing discovery-gate confirmation at specify step 5 is preserved
unchanged — the packet governs FR/AC id &lt;strong&gt;numbering&lt;/strong&gt;, not whether the human
confirms discovery. &lt;code dir=&quot;auto&quot;&gt;source_tool&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;source_id&lt;/code&gt; remain free-form strings;
the schema encodes no producer-specific types (ticket keys, story ids, or
similar).&lt;/p&gt;
&lt;p&gt;This intake-side &lt;strong&gt;handoff packet&lt;/strong&gt; is a distinct artifact from the
mission-side &lt;strong&gt;handoff package&lt;/strong&gt; — the dossier/replay export produced by
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/dossier/&lt;/code&gt; (mission 045,
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/045-mission-handoff-package-version-matrix/&lt;/code&gt;). The packet seeds a
mission; the package is emitted after one. Same surface word, opposite
direction of travel — name the one meant.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Producers that emit v1 packets get stable, traceable FR/AC ids instead of
re-minted ones, and the producer-native id survives as a recorded trace.&lt;/li&gt;
&lt;li&gt;Every other intake path is byte-for-byte unchanged; there is no migration
and no schema bump for projects that never emit a packet.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative-and-accepted-trade-offs&quot;&gt;Negative and accepted trade-offs&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Spec Kitty now commits to a producer-facing contract surface it must
version and eventually retire deliberately, rather than being free to
reshape intake parsing at will.&lt;/li&gt;
&lt;li&gt;The contract is not yet registered in
&lt;code dir=&quot;auto&quot;&gt;docs/contracts/contract-registry.yaml&lt;/code&gt; — that registry’s &lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt; vocabulary
is currently &lt;code dir=&quot;auto&quot;&gt;fallback_name&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;retired_literal&lt;/code&gt; only, with no
payload/intake-contract kind to register this record under. Adding that
&lt;code dir=&quot;auto&quot;&gt;kind&lt;/code&gt; and registering this contract is a follow-up (&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/3446&quot;&gt;#3446&lt;/a&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives Considered&lt;/h2&gt;
&lt;h3 id=&quot;require-a-mandatory-structured-format&quot;&gt;Require a mandatory structured format&lt;/h3&gt;
&lt;p&gt;Rejected. Forcing every intake to be YAML-frontmatter-bearing would break the
compatibility surface this contract exists to protect: “prose is always
valid input” must remain true for every producer that never adopts the
overlay.&lt;/p&gt;
&lt;h3 id=&quot;encode-producer-specific-vocabulary-in-the-schema&quot;&gt;Encode producer-specific vocabulary in the schema&lt;/h3&gt;
&lt;p&gt;Rejected. Modeling ticket types, story shapes, or use-case ids directly in
the frontmatter schema would couple Spec Kitty to a specific upstream tool’s
domain model. &lt;code dir=&quot;auto&quot;&gt;source_tool&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;source_id&lt;/code&gt; stay deliberately free-form so any
producer can populate them without a schema change.&lt;/p&gt;
&lt;h2 id=&quot;references&quot;&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Contract: &lt;a href=&quot;/contracts/handoff-packet-v1/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/contracts/handoff-packet-v1.md&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/pull/3379&quot;&gt;PR #3379&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
