Kobold 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3365a9b108ba3abccb20d4040f8f10c2b3cfeafaffcb1eab97f8bb6ec31c96f2
-  data.tar.gz: d5449335967f96c07777761a95a5de46b4a61857fd0c782b85dbfc8ab9ef7c20
+  metadata.gz: aac2217a763dde7fd61d408dfc0886bba7ccb4576900aefb9f58b78854c9b009
+  data.tar.gz: 82b0b9c56e06172b08fa7046d0dd7042754e92262ad06a5b9fa66ddedb3e0fd3
 SHA512:
-  metadata.gz: 65f41daea3213f01c72847b0cf4e51cc86580d1c514f3d89575273fb1f0437c720dce10bbc455c59ef8fa733eb59f433c78c2102cbd88856dab15ac4068422eb
-  data.tar.gz: 2e12df3ae02950f89743efe353855c86409073d5031af3eba41c8c1ab4e5d7dc18d85e3e3546fbcf05c799ceef49cb09b222b7877d86193d6c4d120c758f0281
+  metadata.gz: 5d68f94b8a24f390c1a4d7bdad1e686cefa9321abac43e6e3a0dc5a3dea7dfe3d1df659f46f6d6910c466da2f05f64b524d661b64593a58b660111894fba0491
+  data.tar.gz: bdabb4d325e525b4f282f40f2f9804243f6044b693458b4250c832bd2b43d14f959f4684a25173a30c44a6c91d1d71ac11ac811cc8b39ef7a8d1ff3c24eb9178

data/.rspec

@@ -0,0 +1,5 @@
+--require spec_helper
+--format documentation
+--format documentation --out tmp/reports/rspec_results.txt
+--format html --out tmp/reports/rspec_results.html
+--color

data/.rubocop.yml

@@ -1,5 +1,10 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  Exclude:
+    - 'references/**/*'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
 
 Style/StringLiterals:
   Enabled: true
@@ -9,5 +14,20 @@ Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
 
+Style/Documentation:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - 'lib/Kobold.rb'
+
 Layout/LineLength:
   Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/MethodLength:
+  Exclude:
+    - 'spec/**/*'

data/.rules/bugs/untestable.md

@@ -0,0 +1,27 @@
+# Untestable Bugs
+
+These bugs require architectural changes and cannot be reliably caught by unit tests.
+
+---
+
+## 1. TOCTOU race in registry read/write (Low)
+
+**File:** `lib/Kobold/database.rb` — `registry`, `write_registry`
+
+Every call to `registry` re-reads and re-parses `registry.toml` from disk. Methods like `register_repo` and `unregister_repo` do a read-modify-write cycle without any locking. If multiple processes or threads operate on the same database concurrently, one process's write can silently overwrite another's.
+
+**Impact:** Safe for single-process CLI use. Dangerous if the Ruby API is used from multiple processes or threads (e.g., the AI orchestrator spawning parallel subagents that share a database).
+
+**Fix:** Add file locking (`File.flock`) around registry read/write operations, or cache the registry in memory with a write-through strategy.
+
+---
+
+## 2. Non-bare clone wastes disk space (Medium)
+
+**File:** `lib/Kobold/git_ops.rb` — `clone`, `lib/Kobold/repo.rb` — `clone`, `cloned?`
+
+The design describes cached repos as "bare-ish clones," but `GitOps.clone` performs a normal (non-bare) clone via `Git.clone(url, path)`. This creates a full working tree checkout inside the source cache directory that is never used, wasting disk space. Additionally, if anyone modifies files in the source working tree, it could cause confusion with worktree operations.
+
+**Impact:** Every cached repo consumes roughly double the disk space needed. For large repos (e.g., raylib), this adds up.
+
+**Fix:** Clone with `bare: true` (or `mirror: true`) and update `Repo#cloned?` to check for bare-repo markers (e.g., `HEAD`, `objects/`) instead of `.git`. Also update `GitOps.create_worktree` and `GitOps.open` to handle bare repos correctly (use `repo.repo.path` or `--git-dir` instead of `repo.dir`).

data/.rules/changelog/2026-03/30/01.md

@@ -0,0 +1,55 @@
+# Phase 1 — Internal Refactor and TOML Migration
+
+## Dependencies
+
+- Removed `tty-config` and `inifile` gems
+- Added `toml-rb ~> 3.0`
+- Relaxed `git` to `~> 2.3`, `tty-option` to `~> 0.3`, `tty-progressbar` to `~> 0.18`
+- Relaxed `rubocop` to `~> 1.0`
+- Bumped `required_ruby_version` to `>= 3.0`
+- Deleted stale `Gemfile.lock`
+- Added `description` to gemspec
+
+## Version
+
+- `VERSION`: `0.3.4` -> `0.4.0`
+- `FORMAT_VERSION`: `0.3.0` -> `0.4.0`
+
+## New Classes/Modules
+
+- `Kobold::Errors` — custom exception hierarchy
+- `Kobold::GitOps` — shared Git operations (clone, open, worktree, fetch, resolve_ref)
+- `Kobold::Config` — TOML .kobold file reader/writer/validator/generator
+- `Kobold::Database` — named cache database with registry.toml
+- `Kobold::Repo` — cached repo with worktree/branch/commit/label management
+- `Kobold::Linker` — symlink creation, validation, cleanup
+
+## Rewritten
+
+- `lib/Kobold.rb` — clean module entry point
+- `lib/Kobold/invoke.rb` — uses new class structure
+- `lib/Kobold/fetch.rb` — uses Database and Repo
+- `lib/Kobold/init.rb` — generates TOML format
+- `exe/kobold` — fixed bugs, added --database flag, error handling
+
+## Deleted
+
+- `lib/Kobold/read_config.rb` (replaced by Config.read)
+- `lib/Kobold/first_time_setup.rb` (replaced by Database#setup)
+
+## Config Format
+
+- `prototyping/.kobold` — converted INI to TOML v0.4.0
+- `sample-project-ideas/.kobold` — converted INI v0.1.0 to TOML v0.4.0
+
+## Bug Fixes
+
+- Fixed `value['sha']` vs `value['commit']` inconsistency
+- Fixed default command dispatch (`cmd.params == "invoke"`)
+- Removed call to non-existent `Kobold.list`
+- Removed `worktree_sha ||= :scoped` hack
+- Stale symlinks now get replaced via Linker
+
+## Types
+
+- Updated `sig/Kobold.rbs` with full signatures for all new classes

data/.rules/changelog/2026-03/30/02.md

@@ -0,0 +1,27 @@
+# Changelog — 2026-03-30 — 02
+
+## Phase 2: Ruby API (High-Level Interface)
+
+### Added
+- **`lib/Kobold/manager.rb`** — New `Kobold::Manager` class providing the high-level Ruby API entry point.
+  - `register` / `unregister` — repo registration
+  - `fetch` / `fetch_all` — single-repo and config-wide fetching
+  - `checkout` — worktree creation with optional symlink
+  - `create_branch` — branch creation with worktree and optional symlink
+  - `remove_worktree` — worktree and symlink removal
+  - `invoke` — full `.kobold` config processing
+  - `init` — `.kobold` file creation
+  - `list_repos` / `list_worktrees` / `list_branches` — listing operations
+  - `generate_config` — programmatic `.kobold` file generation
+  - `clean` — stale worktree cleanup
+  - All methods return structured Hashes/Arrays instead of printing to stdout.
+
+### Changed
+- **`lib/Kobold.rb`** — Added `require_relative "Kobold/manager"`.
+- **`lib/Kobold/invoke.rb`** — Refactored to thin wrapper delegating to `Manager#invoke`.
+- **`lib/Kobold/fetch.rb`** — Refactored to thin wrapper delegating to `Manager#fetch_all`.
+- **`lib/Kobold/init.rb`** — Refactored to thin wrapper delegating to `Manager#init`.
+- **`sig/Kobold.rbs`** — Updated with full `Manager` type signatures and corrected return types for module-level methods.
+
+### Moved
+- **`.rules/plan/plan.md`** → **`.rules/default/plan.md`** — Plan file relocated per user request. Phase 1 and Phase 2 marked as complete.

data/.rules/changelog/2026-03/30/03.md

@@ -0,0 +1,36 @@
+# Phase 3 — CLI Overhaul
+
+## New Files
+
+- `lib/Kobold/cli.rb` — New `Kobold::CLI` class replacing the old `Kobold::Command`. Every subcommand is a thin wrapper around `Kobold::Manager`. Includes custom flag parser, colored output helpers, and structured error handling with human-readable hints.
+
+## Modified Files
+
+- `exe/kobold` — Replaced the old monolithic `Command` class (using `tty-option`) with a 3-line entry point delegating to `Kobold::CLI`.
+- `lib/Kobold.rb` — Added `require_relative "Kobold/cli"`.
+- `Kobold.gemspec` — Removed `tty-option` dependency (no longer used).
+
+## CLI Commands Implemented
+
+- `kobold init` — Create `.kobold` file; supports non-interactive mode with `--repo`, `--source`, `--branch`, `--commit`, `--label`, `--name`, `--dep-dir`.
+- `kobold invoke` — Process `.kobold` and set up all dependencies.
+- `kobold fetch [REPO]` — Fetch single repo or all from `.kobold`.
+- `kobold register REPO --source URL` — Register a repo in the database.
+- `kobold unregister REPO` — Remove a repo from the registry.
+- `kobold checkout REPO` — Create worktree with `--branch`, `--commit`, `--label`, `--dir`.
+- `kobold branch REPO --name NAME` — Create branch with `--from`, `--dir`.
+- `kobold list repos|worktrees|branches [REPO]` — List database contents.
+- `kobold clean` — Remove stale worktrees.
+- `kobold version` — Print version info.
+
+## Global Features
+
+- `--database NAME` flag on all commands (defaults to `default`).
+- Per-command `-h`/`--help` support.
+- Colored terminal output (green checkmarks, blue info, yellow warnings, red errors).
+- Human-readable error messages with suggested-fix hints.
+- Proper exit codes: 0 (success), 1 (error), 2 (usage).
+
+## Removed Dependencies
+
+- `tty-option` — replaced by custom lightweight flag parser for better subcommand support.

data/.rules/changelog/2026-03/30/04.md

@@ -0,0 +1,48 @@
+# Changelog — 2026-03-30 (04)
+
+## Phase 4: Cleanup, Remove, and Lifecycle
+
+### New Features
+
+- **`add` command / `Manager#add`** — Add a dependency to an existing `.kobold` file. Registers and clones the repo if not already cached.
+- **`remove` command / `Manager#remove`** — Remove a dependency from `.kobold`. `--cleanup` flag optionally removes the associated worktree and symlink.
+- **`update` command / `Manager#update`** — Fetch latest and update the commit SHA in `.kobold` to the latest on the specified branch. Supports updating a single dependency or all at once.
+- **`db` command** — Database lifecycle management: `db create`, `db delete`, `db list`.
+- **`config` command** — View or change global settings: `config get-source`, `config set-source`.
+- **`Kobold::Settings` module** — Global user-level settings stored at `~/.local/share/Kobold/config.toml`. Manages default source URL (defaults to `https://github.com`).
+- **Default source URL** — `--source` is now optional for `register`, `add`, and `init` commands; defaults to the configured source (GitHub by default).
+- **Enhanced `clean` command** — Now supports `--purge` flag to remove repos not referenced by any `.kobold` file.
+
+### New Error Classes
+
+- `Kobold::Errors::DependencyNotFound`
+- `Kobold::Errors::DatabaseExists`
+- `Kobold::Errors::LinkError`
+
+### Config Mutations
+
+- `Config#add_dependency`, `#remove_dependency`, `#dependency?`, `#dependency`, `#update_dependency` for in-memory `.kobold` manipulation.
+
+### Database Lifecycle
+
+- `Database.list_databases`, `Database.exists?`, `Database#exists?`, `Database#delete` for managing named databases.
+
+### Repo Enhancements
+
+- `Repo#resolve_branch_head` — resolve branch to latest commit SHA.
+- `Repo#purge` — delete entire repo from cache.
+- `Repo#worktree_path_for` — public worktree path resolver.
+
+### GitOps
+
+- `GitOps.resolve_branch_head` — resolve branch HEAD checking remote then local branches.
+
+### CLI
+
+- Boolean flag support in `parse_flags` for `--cleanup` and `--purge`.
+- `short_sha` helper for displaying truncated commit SHAs.
+- Updated help text for all commands.
+
+### README
+
+- Full rewrite: project description, all CLI commands with examples, build/install instructions.

data/.rules/changelog/2026-03/30/05.md

@@ -0,0 +1,19 @@
+# Changelog — 2026-03-30 #05
+
+## Bug Fixes (High Severity) in `lib/Kobold/repo.rb`
+
+### `create_worktree` — branch HEAD now resolved to full SHA
+- When `branch` is provided without `commit`, the branch HEAD is resolved via `GitOps.resolve_branch_head` so `resolved_sha` is always a real SHA. Previously, the branch name string was used as the SHA, producing incorrect worktree paths for `label + branch` combinations.
+- When no arguments are given, the default branch is detected and used as the `branch` parameter, ensuring the worktree lands in `worktrees/branches/<name>/` instead of falling back to `source_path`.
+
+### `resolve_worktree_path` — removed `source_path` fallback
+- The `else` branch now raises `Errors::GitError` instead of returning `source_path`, preventing accidental worktree creation on (or symlinking to) the shared source cache.
+
+### `worktree_path_for` — commit now resolved to full SHA
+- Resolves the commit via `GitOps.resolve_ref` when the repo is cloned, so the returned path matches what `create_worktree` produces. Previously, the raw short SHA was used, causing path mismatches that broke `Manager#remove` cleanup.
+
+## Documentation
+
+### Filed medium and low severity bugs
+- Created `.rules/bugs/medium.md` (3 bugs: Linker crash on non-symlink, relative symlink comparison, non-bare clone waste).
+- Created `.rules/bugs/low.md` (4 bugs: dead `@registry` variable, TOCTOU races, mixed key types, silent `--database` ignore).

data/.rules/changelog/2026-03/30/06.md

@@ -0,0 +1,16 @@
+# Fix worktree creation "already checked out" error
+
+## Changed
+
+- **`lib/Kobold/git_ops.rb`**
+  - `create_worktree`: Replaced `repo.worktree(path, ref).add` (from the `git` gem) with a direct `Open3.capture3` call using `git worktree add --detach`. The ref is resolved to a full SHA before creating the worktree, which avoids Git's "branch is already checked out" error when the branch (e.g., `master`) is already checked out in the source clone.
+  - `remove_worktree`: Replaced `repo.worktree(path).remove` with `Open3.capture3` using `git worktree remove --force` for consistency with the new `create_worktree` approach.
+  - Added `require "open3"` to support the new implementation.
+
+## Bug
+
+When running `kobold invoke` on a `.kobold` file with a branch-only dependency (e.g., `branch = "master"`), the `git` gem's worktree API would fail with:
+```
+fatal: 'master' is already used by worktree at '.../source'
+```
+This happened because the source clone already has the default branch checked out, and Git refuses to create a second worktree for the same branch. Using `--detach` with a resolved SHA bypasses this restriction.

data/.rules/changelog/2026-03/30/07.md

@@ -0,0 +1,28 @@
+# Changelog — 2026-03-30 #07
+
+## Upgrade git gem from 2.3 to 4.3.1
+
+### Dependencies
+
+- **`git`** — Updated from `~> 2.3` (v2.3.3) to `~> 4.3` (v4.3.1)
+- **`tty-progressbar`** — Removed (no longer used)
+- **`process_executer`** — Transitive dependency updated from v1.3 to v4.0.2 (via git gem)
+
+### API Compatibility Fixes (`lib/Kobold/git_ops.rb`)
+
+- `Git::FailedError` → `Git::Error` in all rescue clauses (v4.x error hierarchy change)
+- `repo.dir.path` → `repo.dir.to_s` in `create_worktree` and `remove_worktree` (`.path` deprecated in v4, removed in v5)
+- Removed threaded TTY::ProgressBar from `clone` and `fetch` — `process_executer` v4.x conflicts with threading around subprocess management. Replaced with simple `puts` messages.
+
+### API Compatibility Fixes (`lib/Kobold/repo.rb`)
+
+- `source_repo.branch.name` → `source_repo.current_branch` in `create_worktree` default branch detection
+- `source_repo.lib.branch_new(name, start_point)` → `Open3.capture3("git", "-C", repo_dir, "branch", name, start_point)` in `create_branch` — v4.x `branch_new` only accepts one argument
+- `rescue Git::FailedError` → `rescue Errors::GitError` with smarter "already exists" check in `create_branch`
+- Added `require "open3"`
+
+### Gemspec
+
+- `git` dependency: `~> 2.3` → `~> 4.3`
+- Removed `tty-progressbar` dependency
+- Added `spec.homepage`

data/.rules/changelog/2026-03/30/08.md

@@ -0,0 +1,29 @@
+# Changelog — 2026-03-30 (08)
+
+## Added: RSpec Integration Test Suite
+
+### New files
+- `.rspec` — RSpec configuration with documentation format and report outputs to `tmp/reports/`
+- `spec/spec_helper.rb` — Test helper with temp directory isolation, constant swapping for `KOBOLD_DIR`, and `GitTestHelpers` module for creating real Git repos on disk
+- `spec/errors_spec.rb` — Tests for all error classes in `Kobold::Errors`
+- `spec/config_spec.rb` — Tests for `Kobold::Config` (validation, read/write round-trip, generate, add/remove/update dependencies)
+- `spec/database_spec.rb` — Tests for `Kobold::Database` (listing, creation, deletion, repo registration, slugify)
+- `spec/settings_spec.rb` — Tests for `Kobold::Settings` (defaults, get/set, read/write, default source)
+- `spec/linker_spec.rb` — Tests for `Kobold::Linker` (symlink creation, stale replacement, unlink, relink, validity)
+- `spec/git_ops_spec.rb` — Tests for `Kobold::GitOps` (clone, open, resolve_ref, worktree create/remove, fetch, resolve_branch_head)
+- `spec/repo_spec.rb` — Tests for `Kobold::Repo` (clone, fetch, worktree creation by branch/commit/label, removal, branch creation, listing, purge)
+- `spec/manager_spec.rb` — Integration tests for `Kobold::Manager` (register, fetch, checkout, create_branch, remove_worktree, invoke, init, list, generate_config, add, remove, update, clean, database lifecycle)
+
+### Modified files
+- `Gemfile` — Added `rspec ~> 3.13` dependency
+- `Gemfile.lock` — Deleted (regenerated by `bundle install` with new dependencies)
+- `Rakefile` — Added `RSpec::Core::RakeTask`, report directory setup, dual-format RuboCop output to `tmp/reports/rubocop_results.html`
+- `.rubocop.yml` — Added `Exclude` for `references/`, `vendor/`, `tmp/` directories to prevent loading `references/ruby-git/.rubocop.yml` which references a missing shared gem
+- `.gitignore` — Added `*.gem` to prevent built gem files from being tracked
+- `Kobold.gemspec` — Added `.gem` file exclusion in `spec.files` to fix "contains itself" validation error
+
+### Summary
+- 126 integration tests covering all modules
+- Tests use real Git repos created in temp directories (no mocking, no network)
+- Every test runs in an isolated temp directory with `KOBOLD_DIR` redirected
+- Reports written to `tmp/reports/` (gitignored)

data/.rules/changelog/2026-03/30/09.md

@@ -0,0 +1,33 @@
+# Changelog — 2026-03-30 (09)
+
+## Fix RuboCop offenses and add Ruby style rules
+
+### `.rubocop.yml`
+- Updated `TargetRubyVersion` from `2.6` to `3.0` to match gemspec `required_ruby_version` (fixes `Gemspec/RequiredRubyVersion`).
+- Disabled `Style/Documentation` globally.
+- Excluded `lib/Kobold.rb` from `Naming/FileName`.
+- Excluded `spec/**/*` from all `Metrics` cops.
+
+### `lib/Kobold/settings.rb`
+- Renamed `set_default_source` to `default_source=` (fixes `Naming/AccessorMethodName`).
+
+### `lib/Kobold/cli.rb`
+- Updated call site from `Settings.set_default_source(...)` to `Settings.default_source = ...`.
+- Split two lines exceeding 120-char limit in `cmd_update` (fixes `Layout/LineLength`).
+- Removed redundant empty `else` clause in `parse_flags` (fixes `Style/EmptyElse`).
+- Reverted autocorrect bug: restored `$stderr.puts` in `warn`, `error`, `hint` methods with `rubocop:disable Style/StderrPuts` to prevent infinite recursion.
+
+### `spec/settings_spec.rb`
+- Updated test references from `set_default_source` to `default_source=`.
+
+### `spec/spec_helper.rb`
+- Reverted autocorrect bug: restored `stub_const` approach instead of manual `remove_const`/`const_set`.
+
+### `spec/config_spec.rb`
+- Added blank line after `require "English"`.
+
+### `sig/Kobold.rbs`
+- Updated RBS signature from `set_default_source` to `default_source=`.
+
+### `.rules/default/rubocop.md` (new)
+- Created agent rules file documenting all RuboCop Metrics constraints (MethodLength, AbcSize, CyclomaticComplexity, PerceivedComplexity, ClassLength, BlockNesting, ParameterLists) with examples and mitigation strategies.

data/.rules/changelog/2026-03/30/10.md

@@ -0,0 +1,12 @@
+# Changelog — 2026-03-30 (10)
+
+## Fix spec_helper const swap and RuboCop spec exclusions
+
+### `spec/spec_helper.rb`
+- Replaced `stub_const` (not available in `around` hooks) with manual `remove_const`/`const_set` approach using `ensure` block for safe constant restoration.
+
+### `.rubocop.yml`
+- Fixed Metrics exclusion for spec files: department-level `Metrics:` exclude doesn't propagate to individual cops. Replaced with explicit `Metrics/BlockLength` and `Metrics/MethodLength` exclusions for `spec/**/*`.
+
+### `.rules/default/rubocop.md` (new in 09)
+- Created agent rules file documenting all RuboCop Metrics constraints with examples and mitigation strategies.

data/.rules/changelog/2026-03/30/11.md

@@ -0,0 +1,47 @@
+# Changelog — 2026-03-30 #11
+
+## Fix all 94 RuboCop offenses across 4 source files
+
+### Summary
+Large refactoring pass to eliminate all 94 RuboCop convention violations
+(Metrics/ClassLength, MethodLength, AbcSize, CyclomaticComplexity,
+PerceivedComplexity, ParameterLists, BlockNesting, Layout, Naming, Style).
+
+All 126 rspec tests continue to pass with zero failures.
+
+### Files changed
+
+**`lib/Kobold/cli.rb`** — Reduced from 774-line monolithic class to a thin
+~100-line shell. Dispatch converted from case/when to hash table.
+
+**New CLI modules extracted:**
+- `lib/Kobold/cli/output.rb` — success/info/warn/error/hint helpers
+- `lib/Kobold/cli/flag_parser.rb` — global and subcommand flag parsing
+- `lib/Kobold/cli/error_handling.rb` — error dispatch table and reporters
+- `lib/Kobold/cli/init_commands.rb` — init, invoke commands
+- `lib/Kobold/cli/repo_commands.rb` — fetch, register, unregister commands
+- `lib/Kobold/cli/checkout_commands.rb` — checkout, branch commands
+- `lib/Kobold/cli/list_commands.rb` — list repos/worktrees/branches
+- `lib/Kobold/cli/lifecycle_commands.rb` — clean, add, remove commands
+- `lib/Kobold/cli/update_commands.rb` — update command
+- `lib/Kobold/cli/admin_commands.rb` — db, config, version commands
+
+**`lib/Kobold/manager.rb`** — Reduced from 313-line class to ~100-line shell.
+
+**New Manager modules extracted:**
+- `lib/Kobold/manager/registration.rb` — register/unregister
+- `lib/Kobold/manager/fetching.rb` — fetch/fetch_all
+- `lib/Kobold/manager/checkout.rb` — checkout, create_branch, remove_worktree
+- `lib/Kobold/manager/invoking.rb` — invoke (process .kobold files)
+- `lib/Kobold/manager/lifecycle.rb` — add, remove, update, update_all
+- `lib/Kobold/manager/cleaning.rb` — clean, purge, referenced slug collection
+
+**`lib/Kobold/config.rb`** — Split validate into 4 private class methods,
+split generate into 2 helpers. Compacted instance methods.
+
+**`lib/Kobold/repo.rb`** — Extracted worktree path resolution into
+`lib/Kobold/repo/worktree_helpers.rb` module.
+
+### Offense count
+- Before: 94 offenses across 4 files
+- After: 0 offenses across 45 inspected files

data/.rules/changelog/2026-03/30/12.md

@@ -0,0 +1,18 @@
+# Changelog — 2026-03-30 #12
+
+## Bug audit and regression test suite
+
+### Added
+- `spec/bug_regression_spec.rb` — 10 regression tests covering 7 identified bugs:
+  - **Bug 1 (High):** `clean_stale_worktrees` never detects stale worktrees because `list_worktrees` uses `Dir.glob` which only returns existing directories.
+  - **Bug 2 (Medium):** `check_nested_symlink` uses `slug.split("-").last` to derive the symlink name, but the actual symlink is named after the worktree basename (e.g., `"main"`), so cleanup never finds nested symlinks.
+  - **Bug 3 (Medium):** `Linker.link` raises raw `Errno::EEXIST` when a regular file or directory exists at the destination.
+  - **Bug 4 (Low):** `Database#setup` references unset `@registry` instance variable (dead code, guarded by `unless File.file?`).
+  - **Bug 5 (Low):** Mixed symbol/string keys in `CLI#build_init_dep` dep hash.
+  - **Bug 6 (Low):** `--database` flag after the command name is silently ignored.
+  - **Bug 7 (Medium):** `Linker.link` relative symlink target comparison resolves against `Dir.pwd` instead of the symlink's parent directory, causing false-negative staleness checks.
+- `.rules/bugs/untestable.md` — documents 2 architectural bugs not coverable by unit tests (TOCTOU registry race, non-bare clone disk waste).
+
+### Removed
+- `.rules/bugs/low.md` — replaced by regression tests and `untestable.md`.
+- `.rules/bugs/medium.md` — replaced by regression tests and `untestable.md`.

data/.rules/changelog/2026-03/30/13.md

@@ -0,0 +1,36 @@
+# Fix 7 bug regressions and RuboCop offenses
+
+## Bug fixes
+
+### Bug 1: Stale worktrees not detected by clean
+- `Repo#list_worktrees` now queries `git worktree list --porcelain` in addition to disk glob, so worktrees whose directories were manually deleted are still discovered and pruned.
+
+### Bug 2: Nested symlink cleanup fails for dir ending with /
+- `link_dep_dir` in `Invoking` now preserves the trailing `/` after `File.expand_path`, so symlinks are correctly created inside the directory.
+- `check_nested_symlink` in `Lifecycle` now scans `Dir.children` for actual symlinks instead of guessing the name from `slug.split("-").last`.
+
+### Bug 3: Linker.link raises Errno::EEXIST on regular files
+- `Linker.link` now detects existing regular files and directories at the destination and removes them with `FileUtils.rm_rf` before creating the symlink.
+
+### Bug 6: --database flag ignored after command
+- Added `handle_post_command_arg` in `FlagParser` to recognize `--database` even when placed after the command (e.g. `kobold init --database mydb`).
+
+### Bug 7: Relative symlink false negative in staleness check
+- `Linker#existing_symlink_matches?` now resolves relative symlink targets using `File.expand_path(existing, File.dirname(symlink_path))` instead of `File.expand_path(existing)` which incorrectly resolved relative to `Dir.pwd`.
+
+## RuboCop fixes
+
+- Fixed `Metrics/ModuleLength` in `Lifecycle` module (was 103/100) by condensing methods and removing unused `slug` parameter.
+- Fixed `Layout/ArgumentAlignment` (7 offenses) in spec file by using parenthesized `to(matcher, message)` form.
+- Fixed `Style/BlockDelimiters` (2 offenses) by converting multi-line `expect { }` to `expect do...end`.
+- Fixed `Lint/UselessAssignment` by removing unused `default_db_path` variable.
+- Fixed Ruby parsing ambiguity where `to be true, "msg"` was parsed as `be(true, "msg")` causing ArgumentError.
+
+## Files changed
+
+- `lib/Kobold/repo.rb`
+- `lib/Kobold/linker.rb`
+- `lib/Kobold/manager/lifecycle.rb`
+- `lib/Kobold/manager/invoking.rb`
+- `lib/Kobold/cli/flag_parser.rb`
+- `spec/bug_regression_spec.rb`

data/.rules/changelog/2026-03/30/14.md

@@ -0,0 +1,13 @@
+# Changelog — 2026-03-30 #14
+
+## Removed
+- Deleted `.rules/default/plan.md` from the rules directory.
+
+## Changed
+- `Manager#add` now defaults the dependency name to the repo name (last segment of repo identifier) when no name is provided. E.g. `raysan5/raylib` defaults to `raylib`.
+- `Invoking#link_dep_dir` now uses the dependency name as the symlink basename when `dir` ends with `/`, instead of the worktree directory name (branch). E.g. `external/raylib` instead of `external/master`.
+
+## Updated Tests
+- Added test in `manager_spec.rb` verifying `Manager#add` defaults name to repo name.
+- Added assertion in invoke test confirming symlink basename matches dependency name.
+- Updated Bug 2 regression tests in `bug_regression_spec.rb` to expect dependency name as symlink basename.

data/.rules/changelog/2026-03/30/15.md

@@ -0,0 +1,24 @@
+# Bug audit and fixes
+
+## Removed stale worktree cleaning capability
+- Removed `clean_stale_worktrees`, `clean_repo_worktrees`, and `remove_stale_worktree` from `manager/cleaning.rb`
+- `Manager#clean` now only handles purging unreferenced repos via `--config`
+- Updated `cli/lifecycle_commands.rb`: removed `--purge` flag, `--config` is now required
+- Removed Bug 1 regression test for stale worktree cleaning
+- Updated `manager_spec.rb` `#clean` test to match new interface
+
+## Fixed `Database#setup` dead `@registry` reference
+- `setup` previously referenced `@registry || {}` but `@registry` was never assigned
+- Changed to just `{}` in `database.rb`
+
+## Fixed mixed symbol/string keys in `build_init_dep`
+- Changed `{ name: dep_name, ... }` to `{ "name" => dep_name, ... }` in `cli/init_commands.rb`
+- Added backward-compat test for symbol `:name` key in `bug_regression_spec.rb`
+
+## Fixed `Settings.read` shallow merge bug
+- `defaults.merge(data)` lost nested default keys when user config overrode a parent hash
+- Added `deep_merge` private helper that recursively merges nested hashes
+- Added 2 tests in `settings_spec.rb` proving the fix
+
+## Updated regression test comments
+- Bug 4 and Bug 5 comments updated to reflect fixes applied