import{_ as t,o as s,c as a,a2 as i}from"./chunks/framework.CJEbdX1t.js";const g=JSON.parse('{"title":"Delta Tracking","description":"","frontmatter":{},"headers":[],"relativePath":"concepts/delta-tracking.md","filePath":"concepts/delta-tracking.md"}'),n={name:"concepts/delta-tracking.md"};function o(l,e,d,r,c,h){return s(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="delta-tracking" tabindex="-1">Delta Tracking <a class="header-anchor" href="#delta-tracking" aria-label="Permalink to &quot;Delta Tracking&quot;">​</a></h1><p>Rather than rewriting specs when things change, Specwright tracks changes through status transitions and hidden HTML comments embedded in the spec markdown.</p><h2 id="how-it-works" tabindex="-1">How It Works <a class="header-anchor" href="#how-it-works" aria-label="Permalink to &quot;How It Works&quot;">​</a></h2><p>Each spec section has a hidden status comment that the agent manages:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">## 3. Idempotency Layer</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:idempotency status:done --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:jira:PAY-142 --&gt;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">All payment endpoints must support idempotency keys...</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">### 3.1 Key Generation</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:key-gen status:done --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:jira:PAY-143 --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:realized-in:PR#412 src/payments/keys.ts --&gt;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline;">x</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] Generate UUID v4 idempotency keys on client</span></span>
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-light-text-decoration:underline;--shiki-dark:#DBEDFF;--shiki-dark-text-decoration:underline;">x</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] Store keys in Redis with 24h TTL</span></span></code></pre></div><h2 id="comment-types" tabindex="-1">Comment Types <a class="header-anchor" href="#comment-types" aria-label="Permalink to &quot;Comment Types&quot;">​</a></h2><p>Specwright uses three types of hidden HTML comments:</p><h3 id="status-comments" tabindex="-1">Status Comments <a class="header-anchor" href="#status-comments" aria-label="Permalink to &quot;Status Comments&quot;">​</a></h3><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:system:&lt;section-id&gt; status:&lt;status&gt; --&gt;</span></span></code></pre></div><p>Tracks the current status of a section. Valid statuses:</p><table tabindex="0"><thead><tr><th>Status</th><th>Meaning</th></tr></thead><tbody><tr><td><code>draft</code></td><td>Initial state — requirements not yet finalized</td></tr><tr><td><code>todo</code></td><td>Ready for implementation</td></tr><tr><td><code>in_progress</code></td><td>Work has started</td></tr><tr><td><code>done</code></td><td>All acceptance criteria verified against code</td></tr><tr><td><code>blocked</code></td><td>Waiting on a dependency (optionally: <code>blocked:TICKET-ID</code>)</td></tr><tr><td><code>deprecated</code></td><td>No longer relevant</td></tr></tbody></table><h3 id="ticket-links" tabindex="-1">Ticket Links <a class="header-anchor" href="#ticket-links" aria-label="Permalink to &quot;Ticket Links&quot;">​</a></h3><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:&lt;system&gt;:&lt;ticket-id&gt; --&gt;</span></span></code></pre></div><p>Links a spec section to a ticket in an external system:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:jira:PAY-142 --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:linear:ID-301 --&gt;</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:ticket:github:42 --&gt;</span></span></code></pre></div><h3 id="realization-evidence" tabindex="-1">Realization Evidence <a class="header-anchor" href="#realization-evidence" aria-label="Permalink to &quot;Realization Evidence&quot;">​</a></h3><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:realized-in:PR#&lt;number&gt; &lt;file&gt;:&lt;lines&gt; --&gt;</span></span></code></pre></div><p>The critical addition — the agent writes this when it verifies that code actually implements the spec section, not just when a ticket is closed:</p><div class="language-markdown vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">markdown</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">&lt;!-- specwright:realized-in:PR#412 src/payments/keys.ts:42-60 --&gt;</span></span></code></pre></div><h2 id="status-transitions" tabindex="-1">Status Transitions <a class="header-anchor" href="#status-transitions" aria-label="Permalink to &quot;Status Transitions&quot;">​</a></h2><p>Statuses typically flow in one direction:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>draft → todo → in_progress → done</span></span>
<span class="line"><span>                    ↓</span></span>
<span class="line"><span>                 blocked → in_progress → done</span></span></code></pre></div><p>The agent auto-transitions statuses based on code evidence:</p><ul><li><code>todo</code> → <code>in_progress</code>: When a PR references this section</li><li><code>in_progress</code> → <code>done</code>: When all acceptance criteria are realized</li><li>Any → <code>blocked</code>: When a dependency is unresolved</li></ul><p>PMs can manually set any status. The <code>deprecated</code> status is terminal — the agent stops tracking the section.</p><h2 id="why-hidden-comments" tabindex="-1">Why Hidden Comments? <a class="header-anchor" href="#why-hidden-comments" aria-label="Permalink to &quot;Why Hidden Comments?&quot;">​</a></h2><p>Hidden HTML comments are invisible when rendering the markdown in GitHub, editors, or documentation sites. This means:</p><ol><li><strong>Clean reading experience</strong> — No metadata clutter in the spec</li><li><strong>Git-friendly</strong> — Comments are just text, so they diff and merge normally</li><li><strong>Tool-agnostic</strong> — Any markdown renderer handles them correctly</li><li><strong>Human-editable</strong> — Engineers can manually fix comments if needed</li></ol><p>The agent manages these comments automatically. Engineers rarely need to touch them directly.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><strong>Reference</strong>: <a href="/docs/reference/spec-format.html">Spec Format</a> — formal syntax for all comment types, frontmatter, and ACs</li><li><strong>Guide</strong>: <a href="/docs/guides/writing-specs.html">Writing Specs</a> — how to write specs with proper status lifecycle</li><li><strong>Concept</strong>: <a href="/docs/concepts/living-specs.html">Living Specs</a> — the feedback loop that drives status transitions</li><li><strong>Concept</strong>: <a href="/docs/concepts/coverage.html">Spec Coverage</a> — how realization evidence feeds into coverage metrics</li><li><strong>Reference</strong>: <a href="/docs/reference/cli.html">CLI</a> — <code>specwright start</code> and <code>specwright done</code> for manual transitions</li><li><strong>Reference</strong>: <a href="/docs/reference/mcp.html">MCP Tools</a> — <code>update_section_status</code> and <code>add_realization</code> for agent use</li></ul>`,31)])])}const k=t(n,[["render",o]]);export{g as __pageData,k as default};
