init: auto-create / update .gitignore with a managed solo-mise block

The handoff inbox is session-local. Files there may contain private
context (commands run, paths, error strings) and should not propagate
through git. Only TEMPLATE.md is meant to be tracked.

`solo-mise init` now creates or updates `.gitignore` in the target
with a marker-bounded block that excludes:
  - .claude/memory-handoffs/* (except TEMPLATE.md and .gitkeep)
  - memory/YYYY-MM-DD.md daily session logs
  - memory/handoff-inbox/ review-state directory
  - .solo-mise/logs/ and .solo-mise/scrub-cache/

Idempotency: re-running init replaces only the content between the
`>>> solo-mise gitignore block >>>` and `<<< solo-mise gitignore block <<<`
markers. Rules outside the block are preserved. Tampered block content
is restored on re-run.

CLI: --no-gitignore opts out. Dry-run prints the gitignore action
without writing.

8 new tests cover create-from-scratch, append-to-existing, idempotent
replace, preservation of out-of-block content, --no-gitignore skip,
dry-run no-write, and workspace profile coverage.

Also: drop the wholesale `.claude/` exclude from solo-mise's own
gitignore so the dogfooded TEMPLATE.md gets tracked (the new managed
block handles handoff privacy correctly).

Total tests: 50 passing.

Author: solomonneas

.gitignore

@@ -31,12 +31,35 @@ htmlcov/
 .DS_Store
 Thumbs.db
 
-# claude / agent local state
-.claude/
+# claude / agent local state (side-harness only; solo-mise block below
+# handles the handoff path with TEMPLATE.md kept tracked)
 .codex/
 .openclaw/
 
 # scratch
 /scratch/
 *.bak
 *.tmp
+
+# >>> solo-mise gitignore block >>>
+# Managed by `solo-mise init`. Edit between the markers to customize.
+# Re-running `solo-mise init` replaces only the content between markers.
+
+# Memory handoffs are session-local and may contain private context
+# (commands run, file paths, error strings). The TEMPLATE.md is the
+# only handoff file tracked in git.
+.claude/memory-handoffs/*
+!.claude/memory-handoffs/TEMPLATE.md
+!.claude/memory-handoffs/.gitkeep
+
+# Daily session logs are machine-local raw context. Promote durable
+# findings into memory/cards/ via the handoff flow instead.
+memory/20[0-9][0-9]-[0-1][0-9]-[0-3][0-9].md
+
+# Review inbox: ambiguous handoffs awaiting human triage. Private.
+memory/handoff-inbox/
+
+# solo-mise local state (logs, scrub cache).
+.solo-mise/logs/
+.solo-mise/scrub-cache/
+# <<< solo-mise gitignore block <<<

QUICKSTART.md

@@ -42,8 +42,11 @@ your-project/
     TEMPLATE.md
   hooks/
     pre-push
+  .gitignore     # adds a managed solo-mise block (handoffs, daily logs, review inbox)
 ```
 
+The `.gitignore` block is bounded by `# >>> solo-mise gitignore block >>>` markers so re-running `init` is idempotent and your hand-written rules outside the block are preserved. Pass `--no-gitignore` to skip the gitignore step.
+
 Enable the pre-push hook once:
 
 ```bash

src/solo_mise/cli.py

@@ -40,6 +40,13 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Override the safety guard that refuses to install directly into $HOME.",
     )
+    p_init.add_argument(
+        "--no-gitignore",
+        dest="update_gitignore",
+        action="store_false",
+        default=True,
+        help="Do not create or update the target's .gitignore.",
+    )
     p_init.add_argument("--dry-run", action="store_true", help="Show what would happen.")
 
     # doctor
@@ -112,6 +119,7 @@ def main(argv=None) -> int:
             dry_run=args.dry_run,
             harness=args.harness,
             allow_home=args.allow_home,
+            update_gitignore=args.update_gitignore,
         )
     if cmd == "doctor":
         from . import doctor as doctor_mod

src/solo_mise/init.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import os
+import re
 import shutil
 import sys
 from pathlib import Path, PurePosixPath
@@ -16,13 +17,42 @@
 )
 
 
+GITIGNORE_BEGIN = "# >>> solo-mise gitignore block >>>"
+GITIGNORE_END = "# <<< solo-mise gitignore block <<<"
+
+GITIGNORE_BLOCK = f"""{GITIGNORE_BEGIN}
+# Managed by `solo-mise init`. Edit between the markers to customize.
+# Re-running `solo-mise init` replaces only the content between markers.
+
+# Memory handoffs are session-local and may contain private context
+# (commands run, file paths, error strings). The TEMPLATE.md is the
+# only handoff file tracked in git.
+.claude/memory-handoffs/*
+!.claude/memory-handoffs/TEMPLATE.md
+!.claude/memory-handoffs/.gitkeep
+
+# Daily session logs are machine-local raw context. Promote durable
+# findings into memory/cards/ via the handoff flow instead.
+memory/20[0-9][0-9]-[0-1][0-9]-[0-3][0-9].md
+
+# Review inbox: ambiguous handoffs awaiting human triage. Private.
+memory/handoff-inbox/
+
+# solo-mise local state (logs, scrub cache).
+.solo-mise/logs/
+.solo-mise/scrub-cache/
+{GITIGNORE_END}
+"""
+
+
 def run(
     target: Path,
     profile_id: str = "repo",
     force: bool = False,
     dry_run: bool = False,
     harness: str | None = None,
     allow_home: bool = False,
+    update_gitignore: bool = True,
 ) -> int:
     """Materialize `profile_id` into `target`. Returns process exit code."""
     target = target.expanduser().resolve()
@@ -79,6 +109,10 @@ def run(
             print(f"  dir   {target / d}")
         for entry in files:
             print(f"  file  {target / entry['dst']}")
+        if update_gitignore:
+            gi = target / ".gitignore"
+            verb = "update" if gi.exists() else "create"
+            print(f"  gitignore  {verb} {gi} with solo-mise block")
         return 0
 
     target.mkdir(parents=True, exist_ok=True)
@@ -117,6 +151,12 @@ def run(
         if mode_str:
             dst.chmod(int(mode_str, 8))
 
+    # Update or create .gitignore with the solo-mise block.
+    if update_gitignore:
+        result = _apply_gitignore(target / ".gitignore")
+        if result:
+            print(f"solo-mise: gitignore {result}")
+
     # Post-install notes.
     print(f"solo-mise: installed profile '{profile_id}' to {target}")
     print(f"solo-mise: memory owner -> {memory_owner_name}")
@@ -142,3 +182,35 @@ def _ensure_safe_rel(raw: str, label: str) -> None:
         raise ValueError(f"{label}: absolute paths not allowed: {raw!r}")
     if any(part == ".." for part in p.parts):
         raise ValueError(f"{label}: parent-dir segments not allowed: {raw!r}")
+
+
+def _apply_gitignore(path: Path) -> str:
+    """Create or update `.gitignore` with the solo-mise block.
+
+    Idempotent: a re-run replaces only the content between
+    `GITIGNORE_BEGIN` and `GITIGNORE_END`. Returns a short status word
+    describing what changed (`created`, `appended`, `updated`, `unchanged`).
+    """
+    if not path.exists():
+        path.write_text(GITIGNORE_BLOCK)
+        return f"created {path}"
+
+    existing = path.read_text()
+    block = GITIGNORE_BLOCK.rstrip("\n")
+
+    if GITIGNORE_BEGIN in existing and GITIGNORE_END in existing:
+        # Replace existing block.
+        pattern = re.compile(
+            re.escape(GITIGNORE_BEGIN) + r".*?" + re.escape(GITIGNORE_END),
+            re.DOTALL,
+        )
+        new = pattern.sub(block, existing)
+        if new == existing:
+            return f"unchanged {path}"
+        path.write_text(new)
+        return f"updated {path}"
+
+    # No block present: append. Make sure we land after exactly one blank line.
+    sep = "" if existing.endswith("\n\n") else ("\n" if existing.endswith("\n") else "\n\n")
+    path.write_text(existing + sep + block + "\n")
+    return f"appended to {path}"

tests/test_gitignore.py

@@ -0,0 +1,103 @@
+"""Tests for the auto-gitignore behavior of `solo-mise init`."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from solo_mise import init as init_mod
+
+
+def _read_gi(target: Path) -> str:
+    return (target / ".gitignore").read_text()
+
+
+def test_init_creates_gitignore_when_missing(tmp_target: Path):
+    rc = init_mod.run(target=tmp_target, profile_id="repo")
+    assert rc == 0
+    gi = _read_gi(tmp_target)
+    assert init_mod.GITIGNORE_BEGIN in gi
+    assert init_mod.GITIGNORE_END in gi
+    assert ".claude/memory-handoffs/*" in gi
+    assert "!.claude/memory-handoffs/TEMPLATE.md" in gi
+    assert "memory/handoff-inbox/" in gi
+
+
+def test_init_appends_block_to_existing_gitignore(tmp_target: Path):
+    tmp_target.mkdir()
+    pre_existing = "# project rules\n*.log\n.env\n"
+    (tmp_target / ".gitignore").write_text(pre_existing)
+    rc = init_mod.run(target=tmp_target, profile_id="repo")
+    assert rc == 0
+    gi = _read_gi(tmp_target)
+    assert pre_existing.strip() in gi, "should preserve existing rules"
+    assert init_mod.GITIGNORE_BEGIN in gi
+    assert init_mod.GITIGNORE_END in gi
+    # block appears exactly once
+    assert gi.count(init_mod.GITIGNORE_BEGIN) == 1
+    assert gi.count(init_mod.GITIGNORE_END) == 1
+
+
+def test_init_idempotent_replaces_block(tmp_target: Path):
+    rc = init_mod.run(target=tmp_target, profile_id="repo")
+    assert rc == 0
+    first = _read_gi(tmp_target)
+
+    # Tamper with the block to confirm replacement happens, not append.
+    tampered = first.replace(".claude/memory-handoffs/*", "GARBAGE_LINE")
+    (tmp_target / ".gitignore").write_text(tampered)
+
+    rc = init_mod.run(target=tmp_target, profile_id="repo", force=True)
+    assert rc == 0
+    second = _read_gi(tmp_target)
+    assert ".claude/memory-handoffs/*" in second
+    assert "GARBAGE_LINE" not in second
+    # still exactly one block
+    assert second.count(init_mod.GITIGNORE_BEGIN) == 1
+
+
+def test_init_preserves_user_edits_outside_block(tmp_target: Path):
+    tmp_target.mkdir()
+    pre = "node_modules/\n# user rules\n*.swp\n"
+    (tmp_target / ".gitignore").write_text(pre)
+    init_mod.run(target=tmp_target, profile_id="repo")
+    # Add user content AFTER the block; re-run should keep it.
+    gi_text = _read_gi(tmp_target)
+    gi_text += "\n# after block\n.local-cache/\n"
+    (tmp_target / ".gitignore").write_text(gi_text)
+
+    init_mod.run(target=tmp_target, profile_id="repo", force=True)
+    final = _read_gi(tmp_target)
+    assert "node_modules/" in final
+    assert "*.swp" in final
+    assert ".local-cache/" in final
+
+
+def test_no_gitignore_flag_skips_creation(tmp_target: Path):
+    rc = init_mod.run(target=tmp_target, profile_id="repo", update_gitignore=False)
+    assert rc == 0
+    assert not (tmp_target / ".gitignore").exists()
+
+
+def test_no_gitignore_flag_leaves_existing_alone(tmp_target: Path):
+    tmp_target.mkdir()
+    pre = "# only my rules\n*.tmp\n"
+    (tmp_target / ".gitignore").write_text(pre)
+    rc = init_mod.run(
+        target=tmp_target, profile_id="repo", update_gitignore=False
+    )
+    assert rc == 0
+    assert _read_gi(tmp_target) == pre
+
+
+def test_dry_run_does_not_write_gitignore(tmp_target: Path):
+    rc = init_mod.run(target=tmp_target, profile_id="repo", dry_run=True)
+    assert rc == 0
+    assert not (tmp_target / ".gitignore").exists()
+    assert not tmp_target.exists()
+
+
+def test_workspace_profile_also_adds_block(tmp_target: Path):
+    rc = init_mod.run(target=tmp_target, profile_id="workspace")
+    assert rc == 0
+    gi = _read_gi(tmp_target)
+    assert init_mod.GITIGNORE_BEGIN in gi
+    assert "memory/handoff-inbox/" in gi