feat: report Code Mower setup drift

[jeffhuber]

Summary

• add a read-only migration setup-drift report for existing Code Mower installs
• classify generated setup paths as same, differs, new, repo-only, or missing-from-output
• document cold install versus upgrade flow in README and install docs

Validation

• scripts/dev-python -m unittest tests.test_migration_setup_drift
• scripts/dev-python -m ruff check src/code_mower/migration.py tests/test_migration_setup_drift.py
• scripts/dev-python -m code_mower.cli migration setup-drift --repo-path . --json
• git diff --check
• scripts/dev-python scripts/privacy_scan.py

Risk and rollback

Medium-low. This adds a new read-only migration command and does not change init output or generated workflow semantics. Roll back by reverting this PR.

Data and privacy

No cloud schema changes. The drift report emits only paths, classifications, tracked state, and byte counts. It omits file contents and diffs.

Closes #538. Part of #536.

[jeffhuber]

Claude audit (merge-authority lane)

Head SHA: 2f1bc502d9c29e6f00f2357235f5f5c25292dfc6
Findings: P0=0, P1=0, P2=0, P3=0 (blocker policy: any P0/P1/P2 -> BLOCKED)

Claude Audit: PASS

Summary:

New code-mower migration setup-drift command adds read-only drift classification (same/differs/new/repo-only/missing-from-output) comparing generated setup output to git-tracked files. Implementation is read-only (no writes), avoids shell injection (subprocess uses list args), and matches the README/docs claims about redacted, content-free reporting. Core classification logic and text rendering are covered by new tests. No P0/P1/P2 correctness, security, or contract issues found.

Findings: none.

[gitar-bot]

💡 Edge Case: Materialization errors bucketed as "missing-from-output"

In _generated_setup_files_from_plan, any OSError/KeyError/ValueError while rendering a generated file silently stores generated[path] = None, which _classify_setup_drift then labels "missing-from-output" — the same bucket used for files the plan intentionally does not produce. A real template rendering failure is thus indistinguishable from an expected omission, hiding the error from the operator running the drift report. Consider surfacing rendering failures under a distinct classification (or capturing the exception message) so genuine errors aren't masked.

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

💡 Edge Case: Negative --limit yields wrong text truncation/count

render_setup_drift_text uses changed[:limit] and remaining = len(changed) - limit with no lower bound, and --limit (argparse type=int) accepts negatives. A negative limit slices off the tail of the list and computes an inflated "... N more" count, producing misleading output. Validate/clamp limit to >= 0 (e.g. max(0, limit)) before slicing.

Clamp limit to a non-negative value at the top of the function.:

def render_setup_drift_text(payload: dict[str, Any], *, limit: int = 50) -> str:
    limit = max(0, limit)

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

💡 Edge Case: Tracked-but-deleted file labeled "new" with tracked=True

In _classify_setup_drift, a path that is tracked in git but absent from the working tree (repo_is_tracked true, repo_exists false) falls into the else branch and is emitted as classification "new" with tracked=True — a contradictory state, since "new" is meant for paths not yet present. This is an edge case (deleted-but-tracked file that the generator also produces), but it can confuse the drift interpretation. Consider handling the tracked-but-missing case explicitly.

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

Code Review 👍 Approved with suggestions 0 resolved / 3 findings

Adds a read-only migration command to report Code Mower setup drift, classifying generated files as same, differs, new, repo-only, or missing-from-output. The implementation is solid and low-risk, but consider addressing three minor edge cases: materialization errors are silently bucketed as

💡 Edge Case: Materialization errors bucketed as "missing-from-output"

📄 src/code_mower/migration.py:431-445 📄 src/code_mower/migration.py:384-392

In _generated_setup_files_from_plan, any OSError/KeyError/ValueError while rendering a generated file silently stores generated[path] = None, which _classify_setup_drift then labels "missing-from-output" — the same bucket used for files the plan intentionally does not produce. A real template rendering failure is thus indistinguishable from an expected omission, hiding the error from the operator running the drift report. Consider surfacing rendering failures under a distinct classification (or capturing the exception message) so genuine errors aren't masked.

💡 Edge Case: Negative --limit yields wrong text truncation/count

📄 src/code_mower/migration.py:527 📄 src/code_mower/migration.py:535-537 📄 src/code_mower/migration.py:648

render_setup_drift_text uses changed[:limit] and remaining = len(changed) - limit with no lower bound, and --limit (argparse type=int) accepts negatives. A negative limit slices off the tail of the list and computes an inflated "... N more" count, producing misleading output. Validate/clamp limit to >= 0 (e.g. max(0, limit)) before slicing.

Clamp limit to a non-negative value at the top of the function.

def render_setup_drift_text(payload: dict[str, Any], *, limit: int = 50) -> str:
    limit = max(0, limit)

💡 Edge Case: Tracked-but-deleted file labeled "new" with tracked=True

📄 src/code_mower/migration.py:382-396

In _classify_setup_drift, a path that is tracked in git but absent from the working tree (repo_is_tracked true, repo_exists false) falls into the else branch and is emitted as classification "new" with tracked=True — a contradictory state, since "new" is meant for paths not yet present. This is an edge case (deleted-but-tracked file that the generator also produces), but it can confuse the drift interpretation. Consider handling the tracked-but-missing case explicitly.

🤖 Prompt for agents

Code Review: Adds a read-only migration command to report Code Mower setup drift, classifying generated files as same, differs, new, repo-only, or missing-from-output. The implementation is solid and low-risk, but consider addressing three minor edge cases: materialization errors are silently bucketed as

1. 💡 Edge Case: Materialization errors bucketed as "missing-from-output"
   Files: src/code_mower/migration.py:431-445, src/code_mower/migration.py:384-392

   In `_generated_setup_files_from_plan`, any `OSError`/`KeyError`/`ValueError` while rendering a generated file silently stores `generated[path] = None`, which `_classify_setup_drift` then labels "missing-from-output" — the same bucket used for files the plan intentionally does not produce. A real template rendering failure is thus indistinguishable from an expected omission, hiding the error from the operator running the drift report. Consider surfacing rendering failures under a distinct classification (or capturing the exception message) so genuine errors aren't masked.

2. 💡 Edge Case: Negative --limit yields wrong text truncation/count
   Files: src/code_mower/migration.py:527, src/code_mower/migration.py:535-537, src/code_mower/migration.py:648

   `render_setup_drift_text` uses `changed[:limit]` and `remaining = len(changed) - limit` with no lower bound, and `--limit` (argparse `type=int`) accepts negatives. A negative limit slices off the tail of the list and computes an inflated "... N more" count, producing misleading output. Validate/clamp `limit` to `>= 0` (e.g. `max(0, limit)`) before slicing.

   Fix (Clamp limit to a non-negative value at the top of the function.):
   def render_setup_drift_text(payload: dict[str, Any], *, limit: int = 50) -> str:
       limit = max(0, limit)

3. 💡 Edge Case: Tracked-but-deleted file labeled "new" with tracked=True
   Files: src/code_mower/migration.py:382-396

   In `_classify_setup_drift`, a path that is tracked in git but absent from the working tree (`repo_is_tracked` true, `repo_exists` false) falls into the `else` branch and is emitted as classification "new" with `tracked=True` — a contradictory state, since "new" is meant for paths not yet present. This is an edge case (deleted-but-tracked file that the generator also produces), but it can confuse the drift interpretation. Consider handling the tracked-but-missing case explicitly.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}