<?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-5-decorator-based-context-validation/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-01-23-5-decorator-based-context-validation/</id>
  <title>Decorator-Based Context Validation</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-5-decorator-based-context-validation/"/>
  <summary>Guards location-sensitive commands with a declarative decorator, blocking the nested-worktree invocations that used to corrupt workspace state silently.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Certain spec-kitty commands must run in specific locations to work correctly:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;implement&lt;/code&gt; must run from &lt;strong&gt;main repository&lt;/strong&gt; (creates worktrees)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; must run from &lt;strong&gt;main repository&lt;/strong&gt; (merges multiple worktree branches)&lt;/li&gt;
&lt;li&gt;Hypothetical workspace commands must run from &lt;strong&gt;inside worktrees&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Running commands in the wrong location causes critical failures:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Nested Worktree Problem&lt;/strong&gt; (Critical):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&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:#82AAFF;--1:#3B61B0&quot;&gt;$&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.worktrees/010-feature-WP02/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Inside worktree&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:#82AAFF;--1:#3B61B0&quot;&gt;$&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP03&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;         &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Tries to create worktree from worktree&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:#919F9F;--1:#5F636F&quot;&gt;# Result: Nested worktrees, corrupted git state, repo unusable&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;strong&gt;Previous solution:&lt;/strong&gt; Manual guard code in each command (20+ lines):&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;python&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:#C792EA;--1:#8844AE&quot;&gt;def&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;implement&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;wp_id&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;str&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;)&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;cwd &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; Path.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;cwd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;().&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;resolve&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:#C792EA;--1:#8844AE&quot;&gt;if&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:#ECC48D;--1:#984E4D&quot;&gt;.worktrees&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;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;in&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; cwd.parts:&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 style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;console.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;print&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:#ECC48D;--1:#984E4D&quot;&gt;Error: Cannot create worktrees from inside a worktree!&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:#919F9F;--1:#5F636F&quot;&gt;# ... 15 more lines of error handling ...&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:#C792EA;--1:#8844AE&quot;&gt;raise&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; typer.&lt;/span&gt;&lt;span style=&quot;--0:#B2CCD6;--1:#096E72&quot;&gt;Exit&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&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:#919F9F;--1:#5F636F&quot;&gt;# ... actual implementation&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;strong&gt;Problems with manual guards:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Verbose boilerplate in every command&lt;/li&gt;
&lt;li&gt;Easy to forget when adding new commands&lt;/li&gt;
&lt;li&gt;Inconsistent error messages&lt;/li&gt;
&lt;li&gt;Could be accidentally removed during refactoring&lt;/li&gt;
&lt;li&gt;No systematic framework for location validation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;How do we enforce location requirements consistently and reliably?&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Critical: Must prevent nested worktrees&lt;/strong&gt; (causes git corruption)&lt;/li&gt;
&lt;li&gt;Need consistent location validation across all commands&lt;/li&gt;
&lt;li&gt;Want declarative approach (clear from function signature)&lt;/li&gt;
&lt;li&gt;Should reduce boilerplate code&lt;/li&gt;
&lt;li&gt;Must provide clear, actionable error messages&lt;/li&gt;
&lt;li&gt;Can’t rely on agent discipline (need enforcement)&lt;/li&gt;
&lt;li&gt;Want reusable framework for all location-aware commands&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; Manual guards in each command (status quo)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Decorator-based validation (&lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Pre-command hooks (global validation)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Wrapper scripts that validate before execution&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: Decorator-based validation”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Declarative (clear from function definition)&lt;/li&gt;
&lt;li&gt;Reusable (single decorator for all commands)&lt;/li&gt;
&lt;li&gt;Can’t be accidentally removed (part of function signature)&lt;/li&gt;
&lt;li&gt;Provides consistent error messages&lt;/li&gt;
&lt;li&gt;Minimal boilerplate (1 line vs 20+ lines)&lt;/li&gt;
&lt;li&gt;Pythonic approach (familiar to developers)&lt;/li&gt;
&lt;li&gt;Easy to test in isolation&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;Prevents nested worktrees automatically (critical bug prevention)&lt;/li&gt;
&lt;li&gt;Consistent error messages across all commands&lt;/li&gt;
&lt;li&gt;Declarative validation (self-documenting code)&lt;/li&gt;
&lt;li&gt;Reduces code duplication (20+ lines → 1 line per command)&lt;/li&gt;
&lt;li&gt;Easy to add validation to new commands&lt;/li&gt;
&lt;li&gt;Clear from function signature what location is required&lt;/li&gt;
&lt;li&gt;Testable in isolation (23 dedicated tests)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Adds decorator import to command files&lt;/li&gt;
&lt;li&gt;Runtime overhead (context detection on each call, ~1ms)&lt;/li&gt;
&lt;li&gt;Could be bypassed by calling function directly (not via CLI)&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Three decorators: &lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@require_worktree&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@require_either&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Error messages include current location, required location, and fix command&lt;/li&gt;
&lt;li&gt;Context detection based on filesystem path analysis&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;Zero instances of nested worktree creation&lt;/li&gt;
&lt;li&gt;No reports of commands running in wrong location&lt;/li&gt;
&lt;li&gt;Error messages successfully guiding users to correct location&lt;/li&gt;
&lt;li&gt;New commands correctly decorated&lt;/li&gt;
&lt;li&gt;Performance impact negligible (&amp;#x3C; 1ms)&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-manual-guards-in-each-command&quot;&gt;Option 1: Manual Guards in Each Command&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Full control over error messages per command&lt;/li&gt;
&lt;li&gt;No framework overhead&lt;/li&gt;
&lt;li&gt;Simple to understand (explicit code)&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;Verbose boilerplate (20+ lines per command)&lt;/li&gt;
&lt;li&gt;Easy to forget for new commands&lt;/li&gt;
&lt;li&gt;Inconsistent error messages&lt;/li&gt;
&lt;li&gt;Can be accidentally removed&lt;/li&gt;
&lt;li&gt;No reusable framework&lt;/li&gt;
&lt;li&gt;Duplicated code across commands&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-decorator-based-validation&quot;&gt;Option 2: Decorator-Based Validation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Declarative (clear from signature)&lt;/li&gt;
&lt;li&gt;Reusable (DRY principle)&lt;/li&gt;
&lt;li&gt;Can’t be accidentally removed&lt;/li&gt;
&lt;li&gt;Consistent error messages&lt;/li&gt;
&lt;li&gt;Minimal boilerplate (1 line)&lt;/li&gt;
&lt;li&gt;Testable in isolation&lt;/li&gt;
&lt;li&gt;Pythonic approach&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;Adds import overhead&lt;/li&gt;
&lt;li&gt;Runtime detection cost (~1ms)&lt;/li&gt;
&lt;li&gt;Could be bypassed if function called directly&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-pre-command-hooks-global-validation&quot;&gt;Option 3: Pre-Command Hooks (Global Validation)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Centralized validation logic&lt;/li&gt;
&lt;li&gt;No per-command changes needed&lt;/li&gt;
&lt;li&gt;Could validate multiple aspects&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;Magic behavior (not clear from function)&lt;/li&gt;
&lt;li&gt;Hard to customize per command&lt;/li&gt;
&lt;li&gt;Difficult to test&lt;/li&gt;
&lt;li&gt;Framework complexity&lt;/li&gt;
&lt;li&gt;Unclear which commands are protected&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-wrapper-scripts&quot;&gt;Option 4: Wrapper Scripts&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Language-agnostic&lt;/li&gt;
&lt;li&gt;Could add shell-level checks&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;Extra layer of indirection&lt;/li&gt;
&lt;li&gt;Harder to maintain&lt;/li&gt;
&lt;li&gt;Not integrated with Python code&lt;/li&gt;
&lt;li&gt;Difficult to test&lt;/li&gt;
&lt;li&gt;Breaks direct Python imports&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;Decorators provided:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt; - Command must run from main repository&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;@require_worktree&lt;/code&gt; - Command must run from inside a worktree&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;@require_either&lt;/code&gt; - Command can run in either location (documentation only)&lt;/li&gt;
&lt;/ul&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Note (2026-09-30):&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;@require_worktree&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;@require_either&lt;/code&gt; and the
&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_CONTEXT&lt;/code&gt; env-var helpers (&lt;code dir=&quot;auto&quot;&gt;set_context_env_vars&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;get_context_env_vars&lt;/code&gt;) never gained a production caller and were removed in
the 2026-09-30 dead-code sweep. Only &lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt; remains.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Context detection:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Checks if “.worktrees” is in current path&lt;/li&gt;
&lt;li&gt;Extracts worktree name and repo root automatically&lt;/li&gt;
&lt;li&gt;Works from any subdirectory&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Environment variables:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_CONTEXT&lt;/code&gt; - “main” or “worktree”&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_WORKTREE_NAME&lt;/code&gt; - Worktree name (if in worktree)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_REPO_ROOT&lt;/code&gt; - Repository root path&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Test coverage:&lt;/strong&gt; 23 tests including critical nested worktree prevention tests&lt;/p&gt;
&lt;h3 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Works with &lt;a href=&quot;/adr/1.x/2026-01-23-2-explicit-base-branch-tracking/&quot;&gt;2026-01-23-2-explicit-base-branch-tracking&lt;/a&gt; for complete context&lt;/li&gt;
&lt;li&gt;Works with &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; for runtime queries&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 ensuring merge runs in main repo&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/core/context_validation.py&lt;/code&gt; - Decorator framework and context detection&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/implement.py:562&lt;/code&gt; - &lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt; applied to implement&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/merge.py:383&lt;/code&gt; - &lt;code dir=&quot;auto&quot;&gt;@require_main_repo&lt;/code&gt; applied to merge&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/unit/test_context_validation.py&lt;/code&gt; - Test suite with critical nesting prevention tests&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;critical-bug-prevention&quot;&gt;Critical Bug Prevention&lt;/h3&gt;
&lt;p&gt;This decision &lt;strong&gt;prevents nested worktrees&lt;/strong&gt;, which corrupts git state:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Nested worktrees make repo unusable&lt;/li&gt;
&lt;li&gt;Requires manual recovery&lt;/li&gt;
&lt;li&gt;Could lose work if not detected&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The decorator framework makes prevention &lt;strong&gt;automatic and unforgeable&lt;/strong&gt; (can’t be accidentally removed during refactoring).&lt;/p&gt;</content>
</entry>
