Prevent local OMC state from leaking into git history

Local setup now seeds git's info/exclude with a default .omc block so
new project installs stop surfacing session/state artifacts as
untracked files. The block explicitly preserves .omc/skills/ because
project-scoped skills are meant to stay version-controlled.

Constraint: Project-level .omc/skills/ must remain trackable
Rejected: Add .omc/ to project .gitignore | would hide project-scoped skills by default
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep default OMC ignores in local git exclude unless project-skill versioning semantics change
Tested: bash -n scripts/setup-claude-md.sh
Tested: npx vitest run src/__tests__/setup-claude-md-script.test.ts
Tested: Manual git-init smoke test of .git/info/exclude behavior
Not-tested: Global setup path beyond ensuring the local-only branch remains gated by mode

Author: Yeachan-Heo

scripts/setup-claude-md.sh

@@ -13,6 +13,38 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SCRIPT_PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 CANONICAL_CLAUDE_MD="${SCRIPT_PLUGIN_ROOT}/docs/CLAUDE.md"
 
+ensure_local_omc_git_exclude() {
+  local exclude_path
+
+  if ! exclude_path=$(git rev-parse --git-path info/exclude 2>/dev/null); then
+    echo "Skipped OMC git exclude setup (not a git repository)"
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$exclude_path")"
+
+  local block_start="# BEGIN OMC local artifacts"
+
+  if [ -f "$exclude_path" ] && grep -Fq "$block_start" "$exclude_path"; then
+    echo "OMC git exclude already configured"
+    return 0
+  fi
+
+  if [ -f "$exclude_path" ] && [ -s "$exclude_path" ]; then
+    printf '\n' >> "$exclude_path"
+  fi
+
+  cat >> "$exclude_path" <<'EOF'
+# BEGIN OMC local artifacts
+.omc/*
+!.omc/skills/
+!.omc/skills/**
+# END OMC local artifacts
+EOF
+
+  echo "Configured git exclude for local .omc artifacts (preserving .omc/skills/)"
+}
+
 # Determine target path
 if [ "$MODE" = "local" ]; then
   mkdir -p .claude
@@ -145,6 +177,10 @@ if ! grep -q '<!-- OMC:START -->' "$TARGET_PATH" || ! grep -q '<!-- OMC:END -->'
   exit 1
 fi
 
+if [ "$MODE" = "local" ]; then
+  ensure_local_omc_git_exclude
+fi
+
 # Extract new version and report
 NEW_VERSION=$(grep -m1 'OMC:VERSION:' "$TARGET_PATH" 2>/dev/null | sed -E 's/.*OMC:VERSION:([^ ]+).*/\1/' || true)
 if [ -z "$NEW_VERSION" ]; then

skills/omc-setup/phases/01-install-claude-md.md

@@ -32,6 +32,8 @@ partially reconstruct CLAUDE.md.
 After running the script, verify the target file contains both markers. If marker validation
 fails, stop and report the failure instead of writing CLAUDE.md manually.
 
+For `local` installs inside a git repository, the script also seeds `.git/info/exclude` with an OMC block that ignores local `.omc/*` artifacts by default while preserving `.omc/skills/` for version-controlled project skills.
+
 **FALLBACK** if curl fails:
 Tell user to manually download from:
 https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md
@@ -46,6 +48,7 @@ If `CONFIG_TARGET` is `local`:
 ```
 OMC Project Configuration Complete
 - CLAUDE.md: Updated with latest configuration from GitHub at ./.claude/CLAUDE.md
+- Git excludes: Added local `.omc/*` ignore rules to `.git/info/exclude` (keeps `.omc/skills/` trackable)
 - Backup: Previous CLAUDE.md backed up (if existed)
 - Scope: PROJECT - applies only to this project
 - Hooks: Provided by plugin (no manual installation needed)

src/__tests__/setup-claude-md-script.test.ts

@@ -100,4 +100,88 @@ This is a summarized CLAUDE.md without markers.
     expect(`${result.stdout}\n${result.stderr}`).toContain('missing required OMC markers');
     expect(existsSync(join(fixture.projectRoot, '.claude', 'CLAUDE.md'))).toBe(false);
   });
+
+  it('adds a local git exclude block for .omc artifacts while preserving .omc/skills', () => {
+    const fixture = createPluginFixture(`<!-- OMC:START -->
+<!-- OMC:VERSION:9.9.9 -->
+
+# Canonical CLAUDE
+Use the real docs file.
+<!-- OMC:END -->
+`);
+
+    const gitInit = spawnSync('git', ['init'], {
+      cwd: fixture.projectRoot,
+      env: {
+        ...process.env,
+        HOME: fixture.homeRoot,
+      },
+      encoding: 'utf-8',
+    });
+    expect(gitInit.status).toBe(0);
+
+    const result = spawnSync('bash', [fixture.scriptPath, 'local'], {
+      cwd: fixture.projectRoot,
+      env: {
+        ...process.env,
+        HOME: fixture.homeRoot,
+      },
+      encoding: 'utf-8',
+    });
+
+    expect(result.status).toBe(0);
+
+    const excludePath = join(fixture.projectRoot, '.git', 'info', 'exclude');
+    expect(existsSync(excludePath)).toBe(true);
+
+    const excludeContents = readFileSync(excludePath, 'utf-8');
+    expect(excludeContents).toContain('# BEGIN OMC local artifacts');
+    expect(excludeContents).toContain('.omc/*');
+    expect(excludeContents).toContain('!.omc/skills/');
+    expect(excludeContents).toContain('!.omc/skills/**');
+    expect(excludeContents).toContain('# END OMC local artifacts');
+  });
+
+  it('does not duplicate the local git exclude block on repeated local setup runs', () => {
+    const fixture = createPluginFixture(`<!-- OMC:START -->
+<!-- OMC:VERSION:9.9.9 -->
+
+# Canonical CLAUDE
+Use the real docs file.
+<!-- OMC:END -->
+`);
+
+    const gitInit = spawnSync('git', ['init'], {
+      cwd: fixture.projectRoot,
+      env: {
+        ...process.env,
+        HOME: fixture.homeRoot,
+      },
+      encoding: 'utf-8',
+    });
+    expect(gitInit.status).toBe(0);
+
+    const firstRun = spawnSync('bash', [fixture.scriptPath, 'local'], {
+      cwd: fixture.projectRoot,
+      env: {
+        ...process.env,
+        HOME: fixture.homeRoot,
+      },
+      encoding: 'utf-8',
+    });
+    expect(firstRun.status).toBe(0);
+
+    const secondRun = spawnSync('bash', [fixture.scriptPath, 'local'], {
+      cwd: fixture.projectRoot,
+      env: {
+        ...process.env,
+        HOME: fixture.homeRoot,
+      },
+      encoding: 'utf-8',
+    });
+    expect(secondRun.status).toBe(0);
+
+    const excludeContents = readFileSync(join(fixture.projectRoot, '.git', 'info', 'exclude'), 'utf-8');
+    expect(excludeContents.match(/# BEGIN OMC local artifacts/g)).toHaveLength(1);
+  });
 });