<?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-04-14-1-sparse-checkout-defense-in-depth/">
  <id>https://docs.spec-kitty.ai/adr/1.x/2026-04-14-1-sparse-checkout-defense-in-depth/</id>
  <title>ADR (2026-04-14): Sparse-Checkout Defence in Depth — Four-Layer Hybrid Preflight + Commit-Layer Backstop</title>
  <updated>2026-04-14T00: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-04-14-1-sparse-checkout-defense-in-depth/"/>
  <summary>Repairs repositories still carrying git state from the retired 0.11-era checkout policy, adding preflight detection at four layers plus a guard against silent file loss.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Between spec-kitty 0.11.0 and 2.x, the CLI actively managed git sparse-checkout
state on user repositories. The sparse-checkout pattern was designed to keep
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; out of execution worktrees so coding agents would not see
planning artifacts as part of their working tree. In 3.0 (PR #347) the
sparse-checkout policy was removed, but &lt;strong&gt;no migration was shipped to unwind
the sparse-checkout state already applied to existing user repositories&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;This produced a latent, fail-silent hazard in the wild. A repository upgraded
from a pre-3.0 CLI continues to carry a sparse-checkout pattern in
&lt;code dir=&quot;auto&quot;&gt;.git/info/sparse-checkout&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;core.sparseCheckout=true&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;.git/config&lt;/code&gt;,
even though the current CLI has no code path that sets them. The CLI also has
no code path that detects or unsets them.&lt;/p&gt;
&lt;p&gt;The hazard manifested concretely in Priivacy-ai/spec-kitty#588: during
&lt;code dir=&quot;auto&quot;&gt;spec-kitty mission merge&lt;/code&gt;, the merge driver stashed working-tree changes,
performed the merge, and then restored the stash on top of a sparse-filtered
index. Paths excluded by the sparse pattern appeared “missing” from the index
relative to the stash, so the stash-pop operation &lt;strong&gt;recorded deletions for
files that were never actually removed from the repository&lt;/strong&gt;. The subsequent
housekeeping commit captured those phantom deletions, silently reverting
content that the preceding merge commit had just introduced.&lt;/p&gt;
&lt;p&gt;Two secondary issues compounded the primary hazard:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The lane-worktree review-lock code path required operators to pass &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;
to approve or reject a review even when the only uncommitted content was
the execution lane’s own &lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; scratch directory — a false alarm
that trained operators to pass &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; reflexively, eroding the guard’s
signal value (Priivacy-ai/spec-kitty#589).&lt;/li&gt;
&lt;li&gt;The retry guidance emitted by the uncommitted-changes guard hardcoded
&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; as the target lane, which was confusing when the guard fired
during transitions to other lanes.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The architectural question posed by these findings is not “how do we patch
&lt;code dir=&quot;auto&quot;&gt;mission merge&lt;/code&gt;.” The question is &lt;strong&gt;where in the command surface should the
defence against sparse-checkout data loss live, given that the root cause is
legacy persistent git state that no single command can be assumed to own?&lt;/strong&gt;&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;The regression is silent and destructive — a commit lands with apparent
success and the data loss is only visible after the fact.&lt;/li&gt;
&lt;li&gt;The cause is &lt;strong&gt;persistent state on the user’s disk&lt;/strong&gt; (git config +
&lt;code dir=&quot;auto&quot;&gt;.git/info/sparse-checkout&lt;/code&gt; pattern) inherited from earlier CLI versions;
any single-command patch is incomplete because the same state will re-enter
any other command that performs index manipulation (stash, checkout, rebase).&lt;/li&gt;
&lt;li&gt;Spec-kitty 3.x intentionally has no sparse-checkout feature; the current CLI
has no reason to ever emit or rely on sparse-checkout state.&lt;/li&gt;
&lt;li&gt;A small set of legitimate users may have independently configured
sparse-checkout for their own reasons; they need an explicit escape hatch
rather than a blanket block.&lt;/li&gt;
&lt;li&gt;The fix must be deployable without requiring users to run a separate
migration command first — the next routine spec-kitty invocation should
either detect and remediate, or at minimum refuse to proceed silently.&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;Option A — Pure merge-only preflight: gate &lt;code dir=&quot;auto&quot;&gt;mission merge&lt;/code&gt; on a sparse-checkout
detection result.&lt;/li&gt;
&lt;li&gt;Option B — Blanket preflight gate on every state-mutating command.&lt;/li&gt;
&lt;li&gt;Option C — Four-layer hybrid: hard block at the two highest-leverage entry
points, universal commit-layer backstop, session-scoped warning elsewhere,
and &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt; as the primary discovery and remediation surface.&lt;/li&gt;
&lt;li&gt;Option D — Reintroduce sparse-checkout as a supported feature and fix the
stash-pop flow around it.&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: Option C — four-layer hybrid.&lt;/strong&gt;&lt;/p&gt;
&lt;h3 id=&quot;decision&quot;&gt;Decision&lt;/h3&gt;
&lt;p&gt;The defence is composed of four independent layers. Each layer has a distinct
role, and the composition is deliberate: removing any single layer leaves a
real regression path uncovered.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Layer 1 — Hard block at &lt;code dir=&quot;auto&quot;&gt;mission merge&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt;
(WP05).&lt;/strong&gt; These are the two highest-blast-radius entry points: merge
integrates multiple lanes into the target branch, and implement creates or
updates the lane worktree that carries per-WP work. Both run a
sparse-checkout preflight and fail closed on detection unless the operator
passes &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt;. Merge additionally performs a post-merge
refresh and invariant check to catch any phantom-deletion commit before it
leaves the integration branch.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Layer 2 — Universal commit-layer backstop in &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; (WP01).&lt;/strong&gt;
Independent of any preflight, &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; inspects the staging area for
any path outside the expected set (determined from the commit’s intended
scope) and aborts the commit with a diagnostic if a mismatch is found. This
is the layer that catches the sparse-stash-pop phantom-deletion cascade
regardless of which command initiated it, and it cannot be bypassed by
command flags. It is the backstop that makes the mission recoverable even
if a future command path forgets to call the preflight.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Layer 3 — Session-scoped warning at other state-mutating CLI surfaces
(WP06).&lt;/strong&gt; Review-lock transitions (&lt;code dir=&quot;auto&quot;&gt;approve&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reject&lt;/code&gt;) and task-command
sessions emit a one-shot session warning when sparse-checkout state is
detected. These surfaces do not block (blocking would be redundant with
Layer 2 at the commit boundary and would degrade UX), but they surface the
condition early, before the operator wastes a commit cycle. The warning is
emitted at most once per process.&lt;/p&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Layer 4 — &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt; is the discovery and remediation surface
(WP04).&lt;/strong&gt; The &lt;code dir=&quot;auto&quot;&gt;sparse-checkout&lt;/code&gt; finding is surfaced in &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; output with
a &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; action that removes &lt;code dir=&quot;auto&quot;&gt;core.sparseCheckout&lt;/code&gt; from git config, clears
the &lt;code dir=&quot;auto&quot;&gt;.git/info/sparse-checkout&lt;/code&gt; pattern file, and verifies post-fix state.
This is the surface operators are pointed at from the other three layers,
and it is the migration recipe for users on repositories upgraded from
pre-3.0 spec-kitty.&lt;/p&gt;
&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt; flag emits a &lt;code dir=&quot;auto&quot;&gt;WARNING&lt;/code&gt;-level structured log
record (&lt;code dir=&quot;auto&quot;&gt;spec_kitty.override.sparse_checkout&lt;/code&gt;) at use time but does not
currently emit a durable audit event. Adding a durable audit event requires
coordinated work in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;spec-kitty-saas&lt;/code&gt;; that follow-up
is tracked as Priivacy-ai/spec-kitty#617.&lt;/p&gt;
&lt;p&gt;In addition:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The review-lock guard no longer requires &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; to approve or reject a
lane-worktree review when the only untracked content is the lane’s own
&lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; scratch directory (Priivacy-ai/spec-kitty#589).&lt;/li&gt;
&lt;li&gt;Retry guidance emitted by the uncommitted-changes guard now names the
actual target lane rather than hardcoded &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Every lane worktree carries a per-worktree git exclude entry for
&lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; written at worktree creation (WP07), so future scratch
content stays invisible to the working-tree guard even in worktrees
initialised before the fix.&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;The #588 data-loss regression is closed at the commit layer (Layer 2)
regardless of which command initiated it, which means the commit-layer
backstop is a safety net even for future command paths that forget to call
the merge/implement preflight.&lt;/li&gt;
&lt;li&gt;The #589 reflexive-&lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; training loop is broken: operators stop learning
to bypass guards, so the guards retain signal value.&lt;/li&gt;
&lt;li&gt;Legitimate sparse-checkout users retain an explicit escape hatch at
&lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt;, with a logged record of its use.&lt;/li&gt;
&lt;li&gt;Repositories upgraded from pre-3.0 spec-kitty have a documented, one-command
migration via &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor --fix sparse-checkout&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The fix is discovery-biased: Layer 3’s session warning surfaces the
condition early on routine activity, so affected repositories find out
before hitting a merge.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; now has a fail-closed assertion that may surface legitimate
edge cases in existing callers that pass an intentionally broader scope;
WP01 included an audit of existing callers, but future callers need to be
aware of the contract.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt; override emits only a structured log record,
not a durable audit event. Log collectors and shell redirection cover the
short-term audit need; durable audit is tracked as #617.&lt;/li&gt;
&lt;li&gt;Four layers is more surface area than a single gate. The trade-off is
deliberate: a single gate would leave a real hazard uncovered.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;This ADR does not reintroduce sparse-checkout as a supported CLI feature;
Option D is explicitly rejected below. The layers exist to defend against
legacy persistent state, not to support current sparse-checkout workflows.&lt;/li&gt;
&lt;li&gt;The four layers share a common detection primitive (WP02) and a common
remediation module (WP03); composition, not duplication, drives the layer
count.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;p&gt;This ADR is considered implemented when all of the following are true:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; aborts commits that stage paths outside the intended scope
(backstop verified by WP01 tests).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mission merge&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; fail closed on detected
sparse-checkout state, with &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt; as the documented
escape hatch (WP05 preflight tests).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty doctor&lt;/code&gt; reports a &lt;code dir=&quot;auto&quot;&gt;sparse-checkout&lt;/code&gt; finding when detection
fires and &lt;code dir=&quot;auto&quot;&gt;--fix sparse-checkout&lt;/code&gt; removes the state and verifies post-fix
(WP04 tests).&lt;/li&gt;
&lt;li&gt;Review-lock approve/reject and task-command sessions emit a one-shot
session warning on detection and do not block (WP06 tests).&lt;/li&gt;
&lt;li&gt;Lane-worktree approve/reject does not require &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; when the only
untracked content is &lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; (WP06 tests mirroring SC-003, SC-004).&lt;/li&gt;
&lt;li&gt;Retry guidance names the actual target lane rather than hardcoded
&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; (WP06 tests).&lt;/li&gt;
&lt;/ol&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-a--pure-merge-only-preflight&quot;&gt;Option A — Pure merge-only preflight&lt;/h3&gt;
&lt;p&gt;Add sparse-checkout detection as a precondition on &lt;code dir=&quot;auto&quot;&gt;mission merge&lt;/code&gt; only.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Minimal surface change.&lt;/li&gt;
&lt;li&gt;Targets the exact command where the #588 regression manifested.&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;Misses the lane-worktree inheritance hazard: a worktree created by
&lt;code dir=&quot;auto&quot;&gt;agent action implement&lt;/code&gt; inherits the repository’s sparse-checkout state
and can silently produce the same stash-pop cascade during any index
manipulation inside that worktree.&lt;/li&gt;
&lt;li&gt;Misses the external-pull cascade: a user pulling a merged branch into a
clone that still carries legacy sparse-checkout state experiences the same
class of phantom deletions on subsequent commits.&lt;/li&gt;
&lt;li&gt;Leaves &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; as an unprotected surface: any future command that
composes stash + merge + commit without calling the preflight reintroduces
the hazard.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The hazard is persistent-state-driven, not command-driven.
A per-command gate cannot enumerate all current and future callers.&lt;/p&gt;
&lt;h3 id=&quot;option-b--blanket-preflight-gate-on-every-state-mutating-command&quot;&gt;Option B — Blanket preflight gate on every state-mutating command&lt;/h3&gt;
&lt;p&gt;Gate every command that mutates git state on sparse-checkout detection.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Broad coverage.&lt;/li&gt;
&lt;li&gt;Single mental model (“every state mutation checks first”).&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;Redundant with Layer 2 at the commit boundary; &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; already runs
for every commit path.&lt;/li&gt;
&lt;li&gt;Degrades the UX of the escape hatch: legitimate sparse-checkout users must
pass &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt; at every command, not just the high-blast
entry points.&lt;/li&gt;
&lt;li&gt;Surfaces the block in contexts where detection does not imply imminent
harm (e.g., read-only status queries), training operators to bypass
reflexively — the exact pathology #589 is fixing.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; More surface does not mean more safety. The backstop at the
commit layer already covers what a blanket gate would cover, at lower cost.&lt;/p&gt;
&lt;h3 id=&quot;option-c--four-layer-hybrid&quot;&gt;Option C — Four-layer hybrid&lt;/h3&gt;
&lt;p&gt;Hard block at high-leverage entry points (Layer 1), universal commit-layer
backstop (Layer 2), session-scoped warning elsewhere (Layer 3), and &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt;
as the discovery and remediation surface (Layer 4).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Each layer has a distinct role and a distinct failure mode it covers.&lt;/li&gt;
&lt;li&gt;The commit-layer backstop is the true universal defence; it cannot be
bypassed by command flags and it catches the exact phantom-deletion
signature regardless of initiator.&lt;/li&gt;
&lt;li&gt;High-leverage commands fail closed with actionable guidance; low-leverage
commands surface the condition without blocking.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; is the single migration entry point, which is the correct surface
for legacy-state remediation across all spec-kitty projects.&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;More surface area than a single gate.&lt;/li&gt;
&lt;li&gt;Requires operators to understand the layer composition to diagnose edge
cases — documented in the status-model docs and the recovery recipe in
&lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Chosen:&lt;/strong&gt; It is the only option that covers the full hazard surface
(merge, implement, lane-worktree inheritance, external-pull cascade, future
command paths) while preserving a clean escape hatch for legitimate use and
a single migration surface for legacy repositories.&lt;/p&gt;
&lt;h3 id=&quot;option-d--reintroduce-sparse-checkout-as-a-supported-feature&quot;&gt;Option D — Reintroduce sparse-checkout as a supported feature&lt;/h3&gt;
&lt;p&gt;Restore the 0.11.0-era sparse-checkout management code and fix the stash-pop
flow around it.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Preserves the original motivation (keep &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; out of execution
worktrees).&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;Explicitly out of scope per C-001 of the mission spec: spec-kitty 3.x
intentionally has no sparse-checkout feature; the per-worktree exclude
mechanism (WP07) covers the original motivation at lower cost.&lt;/li&gt;
&lt;li&gt;Does not help users on repositories that have legacy sparse-checkout state
from earlier CLI versions — those users are already in the hazardous state,
and bringing back the feature does not migrate them off it.&lt;/li&gt;
&lt;li&gt;Reintroduces a large failure surface that 3.x intentionally removed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Why Rejected:&lt;/strong&gt; The goal is not to restore sparse-checkout; the goal is to
defuse the legacy state it left behind.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;Relevant repository evidence:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Primary regression: Priivacy-ai/spec-kitty#588 — phantom-deletion cascade
in &lt;code dir=&quot;auto&quot;&gt;spec-kitty mission merge&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Review-lock reflexive-&lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt; fix: Priivacy-ai/spec-kitty#589.&lt;/li&gt;
&lt;li&gt;Durable audit event follow-up: Priivacy-ai/spec-kitty#617.&lt;/li&gt;
&lt;li&gt;Mission spec: &lt;code dir=&quot;auto&quot;&gt;kitty-specs/legacy-sparse-and-review-lock-hardening-01KP54ZW/spec.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Decision Log (spec §12) records the three entries that back this ADR:
the layered-hybrid decision, the &lt;code dir=&quot;auto&quot;&gt;--allow-sparse-checkout&lt;/code&gt; vs &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;
distinction, and the structured-log-instead-of-durable-audit decision.&lt;/li&gt;
&lt;li&gt;Historical context commits:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;d0c158f4&lt;/code&gt; (v0.11.0) — introduction of sparse-checkout management.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;8f5b56ed&lt;/code&gt; (v0.15.0) — sparse-checkout consolidation into the VCS layer.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;5d238657&lt;/code&gt; (v3.0.0, PR #347) — removal of the sparse-checkout policy
without a migration for existing user repositories (the root cause of
the persistent-state hazard).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Implementation surfaces (by WP):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;WP01 — &lt;code dir=&quot;auto&quot;&gt;safe_commit&lt;/code&gt; backstop (Layer 2).&lt;/li&gt;
&lt;li&gt;WP02 — sparse-checkout detection primitive, session warning, preflight API
(shared foundation for Layers 1, 3, 4).&lt;/li&gt;
&lt;li&gt;WP03 — remediation module (shared foundation for Layer 4’s &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;WP04 — &lt;code dir=&quot;auto&quot;&gt;doctor&lt;/code&gt; finding + &lt;code dir=&quot;auto&quot;&gt;--fix&lt;/code&gt; action (Layer 4).&lt;/li&gt;
&lt;li&gt;WP05 — merge and implement preflights + post-merge refresh (Layer 1).&lt;/li&gt;
&lt;li&gt;WP06 — review-lock approve/reject without &lt;code dir=&quot;auto&quot;&gt;--force&lt;/code&gt;, task-command session
warning (Layer 3 + #589 fix).&lt;/li&gt;
&lt;li&gt;WP07 — per-worktree &lt;code dir=&quot;auto&quot;&gt;.spec-kitty/&lt;/code&gt; exclude writer + once-per-process
external session warning (Layer 3 hardening).&lt;/li&gt;
&lt;li&gt;WP09 — this ADR, &lt;code dir=&quot;auto&quot;&gt;CHANGELOG.md&lt;/code&gt; recovery recipe, and the #588 diagnostic
comment (FR-021, FR-022).&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
