<?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-12-1-baseline-captured-at-for-review-not-claim/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-12-1-baseline-captured-at-for-review-not-claim/</id>
  <title>ADR: the test baseline is captured at for_review, at the lane fork point, not at the claim</title>
  <updated>2026-10-12T00: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-12-1-baseline-captured-at-for-review-not-claim/"/>
  <summary>Test-baseline capture runs capture-if-missing on the in_progress to for_review edge, at the lane merge-base, lock-free and fail-open; the claim never runs the suite.</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-12&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner).&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/6062&quot;&gt;#6062&lt;/a&gt;
(&lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; hung holding the machine-wide pre-review-gate lock), fixed in
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/pull/6068&quot;&gt;PR #6068&lt;/a&gt;. Related: #2493 (the gate lock).&lt;/p&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;agent action implement&lt;/code&gt; ran the project’s configured baseline test suite synchronously before it
returned. That run reused the &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; gate’s head runner, which wrapped every launch in
&lt;code dir=&quot;auto&quot;&gt;pre-review-gate-run.lock&lt;/code&gt;, the machine-wide lock that serializes concurrent &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; head
runs (#2493). A claim therefore acquired, or queued on, a lock scoped to a different transition.
The claim could wedge (exit 124 under a &lt;code dir=&quot;auto&quot;&gt;timeout&lt;/code&gt;, about 0% CPU) and could block another lane’s
&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; gate.&lt;/p&gt;
&lt;p&gt;The baseline is still needed: the pre-review gate diffs head failures against it so that failures
that already existed on the base are not reported as regressions.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A claim must return promptly after the lane worktree exists and the work package is &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The baseline must describe the code the lane started from, not whatever the base is by the time
the work package reaches review.&lt;/li&gt;
&lt;li&gt;Capture must not couple to a lock that belongs to another transition.&lt;/li&gt;
&lt;li&gt;A capture fault must never refuse a &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; move.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Test-baseline capture runs capture-if-missing on the &lt;code dir=&quot;auto&quot;&gt;in_progress -&gt; for_review&lt;/code&gt; edge, at the
lane’s merge-base with its base branch, lock-free and fail-open; the claim never runs the suite.&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The claim path does not capture. &lt;code dir=&quot;auto&quot;&gt;implement_capture_baseline&lt;/code&gt; became &lt;code dir=&quot;auto&quot;&gt;capture_and_commit_baseline&lt;/code&gt;
because it is no longer implement-only.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;move-task --to for_review&lt;/code&gt; captures when no &lt;code dir=&quot;auto&quot;&gt;baseline-tests.json&lt;/code&gt; exists. A rework cycle finds the
committed artifact and does nothing; an unconfigured &lt;code dir=&quot;auto&quot;&gt;review.test_command&lt;/code&gt; captures nothing.&lt;/li&gt;
&lt;li&gt;The capture ref is &lt;code dir=&quot;auto&quot;&gt;git merge-base &amp;#x3C;lane HEAD&gt; &amp;#x3C;base&gt;&lt;/code&gt; (local refs only, no fetch). If it cannot be
resolved, the base tip is used and a warning is logged.&lt;/li&gt;
&lt;li&gt;Capture runs through &lt;code dir=&quot;auto&quot;&gt;_run_raw_command(serialize=False)&lt;/code&gt; in its own detached worktree, keeping the
group-safe launch and reap, without the gate lock.&lt;/li&gt;
&lt;li&gt;Any fault in capture preparation or the run degrades to no baseline; the gate then reports
&lt;code dir=&quot;auto&quot;&gt;UNVERIFIED_BASELINE&lt;/code&gt; as a warning, exactly as for a never-captured baseline.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The baseline reflects the fork point. The artifact’s &lt;code dir=&quot;auto&quot;&gt;base_commit&lt;/code&gt; records the SHA it was taken at,
so a reader can detect a stale baseline.&lt;/li&gt;
&lt;li&gt;Concurrent captures from different lanes do not serialize on the gate lock.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; head run still serializes on the gate lock (#2493), so a &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; move can
wait on another lane’s head run, but never because of a baseline capture.&lt;/li&gt;
&lt;li&gt;The configured suite now runs at the first &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; of a work package, where blocking is
acceptable, instead of at claim time. The first &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; move is slower by one suite run.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
