<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-04-1-mission-contracts-waiver-in-meta-json/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-04-1-mission-contracts-waiver-in-meta-json/</id>
  <title>ADR: a Mission waives the contracts/ deliverable with a meta.json declaration</title>
  <updated>2026-10-04T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-04-1-mission-contracts-waiver-in-meta-json/"/>
  <summary>Strict accept keeps contracts/ required unless meta.json declares &quot;contracts&quot;: &quot;none&quot; with a non-empty contracts_rationale, read by one fail-closed helper.</summary>
  <content type="html">&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-10-04&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner). Operator triage ruling on #5298 (2026-09-28) and the waiver-shape ruling in the Mission brief (2026-10-04).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5298&quot;&gt;#5298&lt;/a&gt;, Mission &lt;code dir=&quot;auto&quot;&gt;friction-remediation-01M43DRV&lt;/code&gt; (WP02). Parent &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/2017&quot;&gt;#2017&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;The software-dev Mission type declares &lt;code dir=&quot;auto&quot;&gt;paths.deliverables: &quot;contracts/&quot;&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;packs/built-in/missions/software-dev/mission.yaml&lt;/code&gt;. Strict &lt;code dir=&quot;auto&quot;&gt;spec-kitty accept&lt;/code&gt; turns a missing &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; into a blocking path-convention violation (&lt;code dir=&quot;auto&quot;&gt;acceptance/summary_core.py::evaluate_path_conventions&lt;/code&gt;).&lt;/p&gt;
&lt;p&gt;Many legitimate software-dev Missions define no interfaces: test remediation, refactors and docs-adjacent fixes. The operator ruled that roughly a third of Missions hit this. Their only escapes were:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;accept --lenient&lt;/code&gt;, which downgrades every path convention, not just this one;&lt;/li&gt;
&lt;li&gt;an empty &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; placeholder, which #1892 called unintended.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The same file lists &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;artifacts.optional&lt;/code&gt;. That is a separate question (is the artifact expected to exist?) and does not settle whether the deliverable convention applies.&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;A Mission declares that it defines no interface contracts in its &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;:&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;json&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;{&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;contracts&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;none&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;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&quot;contracts_rationale&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C789D6;--1:#7C5686&quot;&gt;Test-drift remediation; this Mission defines no interfaces.&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:#D6DEEB;--1:#403F53&quot;&gt;}&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;One authority.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;specify_cli.core.paths.read_contracts_waiver_from_meta&lt;/code&gt; is the only reader. It is a thin adapter over &lt;code dir=&quot;auto&quot;&gt;load_meta_fail_closed&lt;/code&gt;, like &lt;code dir=&quot;auto&quot;&gt;read_retention_from_meta&lt;/code&gt;. There is no spec-frontmatter or plan-frontmatter source, so no second, disagreeing declaration can exist.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-closed.&lt;/strong&gt; Each of the following is NOT a waiver: any &lt;code dir=&quot;auto&quot;&gt;contracts&lt;/code&gt; value other than the exact string &lt;code dir=&quot;auto&quot;&gt;&quot;none&quot;&lt;/code&gt; (including &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt;, booleans and other casing), and a missing, blank or non-string &lt;code dir=&quot;auto&quot;&gt;contracts_rationale&lt;/code&gt;. Such a declaration keeps the requirement in force and produces a warning naming the problem. A corrupt &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; raises &lt;code dir=&quot;auto&quot;&gt;MissionMetaReadError&lt;/code&gt;, as every fail-closed meta read does.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Where it applies.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;evaluate_path_conventions&lt;/code&gt; remains the only caller of &lt;code dir=&quot;auto&quot;&gt;validate_mission_paths&lt;/code&gt; (gated by &lt;code dir=&quot;auto&quot;&gt;test_lifted_root_validate_mission_paths_single_caller.py&lt;/code&gt;). It passes the waived token down as &lt;code dir=&quot;auto&quot;&gt;waived_artifact_tokens&lt;/code&gt;. The validator skips a declared path only when that path is a mission-artifact path. A build or repository path (&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;) can never be waived.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Auditable.&lt;/strong&gt; An honoured waiver’s rationale is surfaced in the accept warnings (“contracts/ requirement waived by meta.json (contracts: none): …”). A malformed waiver’s warning is attached to the blocking violation text.&lt;/li&gt;
&lt;li&gt;The field is consulted only when &lt;code dir=&quot;auto&quot;&gt;contracts&lt;/code&gt; is both a declared path convention and a declared mission artifact (the case the validator can waive), so accept never claims a waiver it did not apply.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The fields are recorded in &lt;code dir=&quot;auto&quot;&gt;MissionMetaOptional&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/mission_metadata.py&lt;/code&gt;). The software-dev plan prompt (&lt;code dir=&quot;auto&quot;&gt;packs/built-in/missions/mission-steps/software-dev/plan/prompt.md&lt;/code&gt;) tells the planning agent to write the two fields when the Mission defines no interfaces. No CLI flag mints them yet.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Treat &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; as satisfied when the artifact is declared optional.&lt;/strong&gt; Rejected by the operator ruling. It silently makes &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; optional for every software-dev Mission, with no explicit, auditable statement that this Mission defines no interfaces.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-Mission declaration in plan or spec frontmatter.&lt;/strong&gt; Rejected. A planning-document field would be a second source of truth beside &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, which already carries Mission-level policy flags (&lt;code dir=&quot;auto&quot;&gt;retain_branches&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;commit_to_target&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per-Mission declaration in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; (chosen).&lt;/strong&gt; Explicit and auditable, read by one helper, and consistent with the existing flat policy fields.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A no-interface Mission passes strict &lt;code dir=&quot;auto&quot;&gt;accept&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; and without a placeholder directory.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; stays required by default; an unwaived or malformed Mission still blocks.&lt;/li&gt;
&lt;li&gt;A waived &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; is also dropped from the “Optional artifacts missing” warning: the Mission declared it absent on purpose, and the waiver note already says so.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Follow-up candidate, not in scope:&lt;/strong&gt; a &lt;code dir=&quot;auto&quot;&gt;mission create&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;setup-plan&lt;/code&gt; flag to mint the waiver.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
