<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/</id>
  <title>Explicit Base Branch Tracking in Work Package Frontmatter</title>
  <updated>2026-01-23T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/"/>
  <summary>Stores each work package&apos;s base branch in its frontmatter instead of recomputing it from git, making workspace provenance visible, auditable, and recreatable.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;When implementing work packages in isolated worktrees, agents and users need to know which branch a workspace was created from (the “base branch”). This information is critical for:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Understanding dependency relationships&lt;/li&gt;
&lt;li&gt;Debugging merge conflicts&lt;/li&gt;
&lt;li&gt;Validating workspace state&lt;/li&gt;
&lt;li&gt;Recreating workspaces if deleted&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Previously, base branch information was &lt;strong&gt;computed at runtime&lt;/strong&gt; from:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Git worktree tracking branch metadata&lt;/li&gt;
&lt;li&gt;Dependency relationships in frontmatter&lt;/li&gt;
&lt;li&gt;Git queries (&lt;code dir=&quot;auto&quot;&gt;git rev-parse --abbrev-ref @{u}&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This runtime-derived approach created visibility problems:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents couldn’t answer “What is my base branch?” without git queries&lt;/li&gt;
&lt;li&gt;No single source of truth for base branch information&lt;/li&gt;
&lt;li&gt;Debugging dependency chains required manual graph traversal&lt;/li&gt;
&lt;li&gt;Base branch invisible in work package metadata&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;LLM agents need explicit base branch information without git queries&lt;/li&gt;
&lt;li&gt;Users debugging issues need clear base branch visibility&lt;/li&gt;
&lt;li&gt;Workspace recreation requires knowing original base branch&lt;/li&gt;
&lt;li&gt;Dependency tracking needs audit trail&lt;/li&gt;
&lt;li&gt;Git queries are slow and error-prone for agents&lt;/li&gt;
&lt;li&gt;Need single source of truth for base branch information&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Continue runtime derivation (status quo)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Store base branch in WP frontmatter&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Store base branch in git commit message&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Store base branch in separate metadata file&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;Chosen option:&lt;/strong&gt; “Option 2: Store base branch in WP frontmatter”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP frontmatter is already the source of truth for WP metadata&lt;/li&gt;
&lt;li&gt;Visible to agents reading planning artifacts&lt;/li&gt;
&lt;li&gt;Tracked in git history (auditability)&lt;/li&gt;
&lt;li&gt;No new files or infrastructure needed&lt;/li&gt;
&lt;li&gt;Consistent with existing dependency tracking pattern&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Agents can read base branch from frontmatter (no git queries needed)&lt;/li&gt;
&lt;li&gt;Single source of truth for base branch information&lt;/li&gt;
&lt;li&gt;Git history shows when base branch was set/changed&lt;/li&gt;
&lt;li&gt;Enables validation (check if base commit still exists)&lt;/li&gt;
&lt;li&gt;Consistent with existing frontmatter-based metadata pattern&lt;/li&gt;
&lt;li&gt;Simplifies debugging dependency chains&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Frontmatter could diverge from actual git state (if manual branch switching)&lt;/li&gt;
&lt;li&gt;Additional fields in frontmatter (slightly more complex schema)&lt;/li&gt;
&lt;li&gt;Requires updating during workspace creation (minor overhead)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Three new frontmatter fields: &lt;code dir=&quot;auto&quot;&gt;base_branch&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;base_commit&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;created_at&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Fields written automatically during &lt;code dir=&quot;auto&quot;&gt;spec-kitty implement&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Backward compatible (optional fields)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;We’ll validate this decision by:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Agents successfully querying base branch from frontmatter&lt;/li&gt;
&lt;li&gt;No reports of base branch confusion or debugging issues&lt;/li&gt;
&lt;li&gt;Successful workspace recreation using base branch information&lt;/li&gt;
&lt;li&gt;Positive feedback from users about base branch visibility&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-continue-runtime-derivation&quot;&gt;Option 1: Continue Runtime Derivation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No schema changes required&lt;/li&gt;
&lt;li&gt;Minimal implementation effort&lt;/li&gt;
&lt;li&gt;Flexible (no persistent state to manage)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Base branch invisible to agents without git queries&lt;/li&gt;
&lt;li&gt;No audit trail for base branch changes&lt;/li&gt;
&lt;li&gt;Debugging requires inferring from git metadata&lt;/li&gt;
&lt;li&gt;Complex logic to derive base branch correctly&lt;/li&gt;
&lt;li&gt;Error-prone (depends on git state being correct)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-store-base-branch-in-wp-frontmatter&quot;&gt;Option 2: Store Base Branch in WP Frontmatter&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Single source of truth&lt;/li&gt;
&lt;li&gt;Visible to agents reading planning artifacts&lt;/li&gt;
&lt;li&gt;Tracked in git history (auditability)&lt;/li&gt;
&lt;li&gt;No new files or infrastructure&lt;/li&gt;
&lt;li&gt;Consistent with existing metadata patterns&lt;/li&gt;
&lt;li&gt;Enables validation and debugging&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Could diverge from git state&lt;/li&gt;
&lt;li&gt;Additional frontmatter fields&lt;/li&gt;
&lt;li&gt;Minor overhead during workspace creation&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-store-base-branch-in-git-commit-message&quot;&gt;Option 3: Store Base Branch in Git Commit Message&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Already in git history&lt;/li&gt;
&lt;li&gt;No schema changes needed&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Difficult to query programmatically&lt;/li&gt;
&lt;li&gt;Not visible in WP files&lt;/li&gt;
&lt;li&gt;Agents would need to parse git log&lt;/li&gt;
&lt;li&gt;Coupling metadata to git commit messages&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-store-base-branch-in-separate-metadata-file&quot;&gt;Option 4: Store Base Branch in Separate Metadata File&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Doesn’t pollute frontmatter&lt;/li&gt;
&lt;li&gt;Could store additional metadata&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;New file to manage (.kittify/workspace-metadata/ directory)&lt;/li&gt;
&lt;li&gt;Not visible in WP files&lt;/li&gt;
&lt;li&gt;Another file to track and sync&lt;/li&gt;
&lt;li&gt;More complex than using existing frontmatter&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;h3 id=&quot;implementation-summary&quot;&gt;Implementation Summary&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Frontmatter fields added:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;base_branch&lt;/code&gt; - Branch this WP was created from (e.g., “010-feature-WP01” or “main”)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;base_commit&lt;/code&gt; - Git SHA snapshot at creation (for validation)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;created_at&lt;/code&gt; - ISO timestamp when workspace was created&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Test coverage:&lt;/strong&gt; 17 tests validating frontmatter updates, backward compatibility, orphaned detection&lt;/p&gt;
&lt;h3 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/adr/1.x/2026-01-23-3-centralized-workspace-context-storage/&quot;&gt;2026-01-23-3-centralized-workspace-context-storage&lt;/a&gt; - Complements this with runtime context files&lt;/li&gt;
&lt;li&gt;Enables &lt;a href=&quot;/adr/1.x/2026-01-23-4-auto-merge-multi-parent-dependencies/&quot;&gt;2026-01-23-4-auto-merge-multi-parent-dependencies&lt;/a&gt; by providing base branch info&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;code-references&quot;&gt;Code References&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/frontmatter.py:38-52&lt;/code&gt; - Frontmatter schema&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/implement.py:833-845&lt;/code&gt; - Writes base tracking on workspace creation&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/workspace_context.py&lt;/code&gt; - WorkspaceContext dataclass and persistence&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/unit/test_base_branch_tracking.py&lt;/code&gt; - Test suite&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
