<?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-06-15-1-marketplace-descriptor-vs-publish/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-06-15-1-marketplace-descriptor-vs-publish/</id>
  <title>ADR 2026-06-15-1: C-006 Amendment — Declarative `marketplace.json` Descriptor vs. Marketplace Publish</title>
  <updated>2026-06-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-06-15-1-marketplace-descriptor-vs-publish/"/>
  <summary>Narrows constraint C-006 to prohibit install and publish actions only, permitting an inert `marketplace.json` descriptor and dropping the bare `marketplace` guard token.</summary>
  <content type="html">&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;The tool-surface-contract mission (&lt;code dir=&quot;auto&quot;&gt;01KV2K2P&lt;/code&gt;) established &lt;strong&gt;C-006 / FR-016&lt;/strong&gt;: the
plugin-bundle projection and validation path must be &lt;em&gt;inert and declarative&lt;/em&gt; — it
must &lt;strong&gt;never auto-install a bundle&lt;/strong&gt; and &lt;strong&gt;never publish it to a marketplace&lt;/strong&gt;.
The original regression test injected a &lt;code dir=&quot;auto&quot;&gt;marketplace_publish&lt;/code&gt; symbol and asserted
the guard fails; reverting it restored green.&lt;/p&gt;
&lt;p&gt;That guard (&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/tool_surface/providers/test_plugin_bundle.py&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;test_no_install_or_publish_tokens_in_source&lt;/code&gt;) was implemented by scanning bundle
module source for a list of forbidden tokens, which included the &lt;strong&gt;bare token
&lt;code dir=&quot;auto&quot;&gt;marketplace&lt;/code&gt;&lt;/strong&gt;. This was a reasonable proxy for “no marketplace publish” at the
time, because no code legitimately needed to name a marketplace at all.&lt;/p&gt;
&lt;p&gt;This mission (&lt;code dir=&quot;auto&quot;&gt;01KV3NGS&lt;/code&gt;) introduced &lt;strong&gt;FR-023&lt;/strong&gt; (Claude) and &lt;strong&gt;FR-029&lt;/strong&gt; (Codex):
the bundle build must generate a &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;marketplace.json&lt;/code&gt;&lt;/strong&gt; catalog &lt;em&gt;descriptor&lt;/em&gt;
alongside the bundle so a user can later run, by hand:&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;claude plugin marketplace add &amp;#x3C;repo-url-or-path&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:#d6deeb;--1:#403f53&quot;&gt;claude plugin install spec-kitty@spec-kitty-plugins&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;marketplace.json&lt;/code&gt; is a static, declarative manifest written into the output
staging tree (&lt;code dir=&quot;auto&quot;&gt;dist/spec-kitty-plugins/...&lt;/code&gt;). Writing it performs &lt;strong&gt;no install,
no publish, no network I/O&lt;/strong&gt; — it is inert output, exactly like &lt;code dir=&quot;auto&quot;&gt;plugin.json&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The bare-&lt;code dir=&quot;auto&quot;&gt;marketplace&lt;/code&gt; token, however, cannot distinguish “writes a marketplace
&lt;em&gt;descriptor&lt;/em&gt;” (&lt;code dir=&quot;auto&quot;&gt;_write_marketplace_json&lt;/code&gt;, the string literal &lt;code dir=&quot;auto&quot;&gt;&quot;marketplace.json&quot;&lt;/code&gt;)
from “publishes to a marketplace” (&lt;code dir=&quot;auto&quot;&gt;marketplace_publish&lt;/code&gt;). After WP05/WP06
landed, the guard tripped on the legitimate descriptor write — a false positive
that surfaced only once all nine lanes were merged (the per-WP review suites do
not run the &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/tool_surface/providers/&lt;/code&gt; guard).&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;Narrow C-006 to its actual intent: &lt;strong&gt;prohibit install/publish &lt;em&gt;actions&lt;/em&gt;; permit
declarative descriptor &lt;em&gt;output&lt;/em&gt;.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Concretely, the bare &lt;code dir=&quot;auto&quot;&gt;marketplace&lt;/code&gt; token is removed from the guard’s
&lt;code dir=&quot;auto&quot;&gt;_FORBIDDEN_TOKENS&lt;/code&gt;. The remaining tokens (&lt;code dir=&quot;auto&quot;&gt;publish&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;auto_install&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;autoinstall&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;register_plugin&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;enable_plugin&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upload&lt;/code&gt;) continue to enforce
the prohibition — in particular the original &lt;code dir=&quot;auto&quot;&gt;marketplace_publish&lt;/code&gt; regression is
still caught by the &lt;code dir=&quot;auto&quot;&gt;publish&lt;/code&gt; token, and any &lt;code dir=&quot;auto&quot;&gt;*_publish&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;*upload*&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;*auto_install*&lt;/code&gt; action symbol still fails the guard.&lt;/p&gt;
&lt;p&gt;What remains prohibited (unchanged):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Auto-installing a generated bundle into a live agent directory.&lt;/li&gt;
&lt;li&gt;Publishing/uploading a bundle to a remote marketplace.&lt;/li&gt;
&lt;li&gt;Any networked or side-effecting distribution action inside &lt;code dir=&quot;auto&quot;&gt;tool_surface/bundles/&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;What is now explicitly permitted:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Writing a declarative &lt;code dir=&quot;auto&quot;&gt;marketplace.json&lt;/code&gt; catalog descriptor into the bundle’s
&lt;code dir=&quot;auto&quot;&gt;dist/&lt;/code&gt; staging tree (FR-023, FR-029). It is inert data the operator consumes
manually via &lt;code dir=&quot;auto&quot;&gt;marketplace add&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;WP05/WP06 code is unchanged; the bundle projectors remain declarative.&lt;/li&gt;
&lt;li&gt;The guard still fails closed on real install/publish actions.&lt;/li&gt;
&lt;li&gt;The “merge-publish layer boundary” ADR
(&lt;code dir=&quot;auto&quot;&gt;2026-06-05-1-merge-publish-layer-boundary.md&lt;/code&gt;) is unaffected: publishing
remains a separate, explicit, out-of-band concern — generating a catalog
descriptor is not publishing.&lt;/li&gt;
&lt;li&gt;Future tightening option (not taken now): relocate descriptor generation into a
dedicated distribution layer so &lt;code dir=&quot;auto&quot;&gt;tool_surface/bundles/&lt;/code&gt; need not name a
marketplace at all. Deferred as unnecessary given the narrowed, intent-aligned
guard.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
