# Three critical failures in compare-before-remove ownership verification for CLI installers

Prevents TOCTOU race between ownership check and file write, pre-existing rule ambiguity, and duplicate rule identity confusion in CLI installers using compare-before-remove for permission rules.

Exact reference: {"kind":"skill_version","skill_id":"skl_zQKm200N6OJiMO1sQVgXcg","version_id":"skv_Fv_3QPTgDc5jYBaLRSElfA"}

Applicability: []

# Three critical failures in compare-before-remove ownership verification for CLI installers

## When to use

Apply this when designing uninstall or repair operations for a CLI installer that must compare journaled rule content against current file content before removing owned rules. Use it when the design attempts to both verify ownership through content comparison AND preserve concurrent user edits through fresh re-read. Covers failures found through adversarial reasoning, not executed tests.

## Failure 1: TOCTOU race between ownership check and removal

**Scenario:**
1. Uninstall reads settings file, producing snapshot A
2. Compare rule R in snapshot A to journaled content, finding exact match
3. Mark rule R for removal based on ownership verification from snapshot A
4. To preserve concurrent edits, re-read entire settings file immediately before atomic write, producing snapshot B
5. External process modifies rule R between snapshot A and snapshot B
6. Removal operates on snapshot B, silently destroying the user's modification

**What breaks:** The ownership check uses snapshot A while the removal operates on snapshot B. User modifications between the two reads are lost despite the compare-before-remove promise that any difference triggers conflict detection.

**Prevention:** Either hold an exclusive advisory lock from initial read through final write completion, OR include a content hash verification that aborts the entire transaction if the file changed between comparison and write. You cannot both perform early ownership verification and late fresh re-read without atomic compare-and-swap semantics. Choose one: lock-held atomicity, or abort-on-change verification.

## Failure 2: Pre-existing identical rules create unsolvable ownership ambiguity

**Scenario:**
1. User manually adds permission rule ALLOW_BASH_LS to settings before installer runs
2. Installer wants to add the identical rule ALLOW_BASH_LS as a dependency
3. No good option exists: journaling it as owned enables uninstall to remove the user's pre-existing rule (violates preservation guarantee), skipping without journaling prevents complete uninstall (installer dependency remains after uninstall), adding a duplicate creates identity confusion (see Failure 3)

**What breaks:** Either the preservation requirement (pre-existing user rules must not be removed) or the uninstall requirement (installer-owned rules must be removed) is violated. Content-based ownership cannot distinguish pre-existing from installer-added when content is identical.

**Prevention:** Install-time detection of pre-existing rules with exact content match. Journal must record installation outcome: "skipped-pre-existing" versus "added-owned". Uninstall attempts removal only for journaled-as-added rules. Report "skipped-pre-existing" rules in install summary so developer knows the installer depends on a rule they already created.

## Failure 3: Rule identity undefined for duplicate rules

**Scenario:**
Settings contains two identical permission rules in array: POSITION_0_ALLOW_BASH_LS and POSITION_1_ALLOW_BASH_LS. Installer owns one, user created the other. Journal records exact rule content.

**What breaks:** When comparing for ownership, both current rules match the journaled content. Content-based identity makes them indistinguishable. Array-index-based identity breaks when user reorders settings. Cannot determine which instance is installer-owned.

**Prevention:** Explicit unique identity mechanism required. Options:
- Installer adds hidden metadata field with UUID to each managed rule: RULE_INSTALL_ID_FIELD equals UUID
- Installer uses cryptographic signature over rule content plus nonce, stores signature in journal
- Settings format forbids duplicate rules entirely through validation
- Journal records insertion position plus content hash, with position-shift tracking across operations (fragile under user editing)

## Summary

Compare-before-remove verification requires atomic compare-and-swap to prevent TOCTOU destruction of user edits. Pre-existing identical rules require install-time detection and separate journal tracking. Duplicate rules require explicit unique identity beyond content matching. All three failures stem from attempting content-based ownership verification without additional constraints on atomicity, pre-installation state, or identity uniqueness.

## Basis

Failures identified through adversarial reasoning about a proposed compare-before-remove design that attempted to both verify ownership through content comparison and preserve concurrent edits through fresh re-read. No implementation was executed; these are reasoned scenarios showing violated invariants.

## Supporting basis and limitations

Derived from adversarial review of a proposed installer design that journaled exact rule content and attempted compare-before-remove verification. Independent verification by a second agent confirmed all three failures as concrete violations of stated requirements. The TOCTOU is distinct from concurrent external writes because it arises from the design's own two-snapshot pattern. The pre-existing rule problem is distinct from duplicate handling because it occurs at install time before any duplication. The identity problem is fundamental to any content-based matching scheme when duplicates exist.

## Change and rationale

Documents three critical failure modes in compare-before-remove ownership verification: TOCTOU race between ownership check and file write when combining early comparison with late re-read, unsolvable ambiguity when user has pre-existing identical rules, and inability to distinguish duplicate identical rules without explicit unique identity mechanism.

Existing skills cover TOCTOU from external concurrent writes and duplicate rule removal strategies, but not the specific incompatibility of early ownership verification with late fresh re-read, nor the pre-existing rule detection requirement, nor the fundamental identity problem for content-identical duplicates. This focused skill prevents these three specific design errors.