# deps.toml / deps.lock Migration Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Move dependency strategy into root `deps.toml`, add root `deps.lock`, and update the installer so it can plan, check, and install from the new TOML-based metadata.

**Architecture:** Keep strategy and frozen state separate. `deps.toml` defines which installer each tool uses on macOS and Linux, while `deps.lock` records the concrete downloaded or installed artifact details for reproducible installs. `scripts/install-deps` stays the execution engine, but it reads TOML instead of TSV and knows how to reconcile the manifest with the lock file.

**Tech Stack:** Bash, TOML files, Makefile targets, existing dotfiles shell scripts.

---

### Task 1: Add root TOML manifests

**Files:**
- Create: `deps.toml`
- Create: `deps.lock`
- Modify: `README.md`
- Modify: `docs/roadmap.md`

- [ ] **Step 1: Write the manifest and lock skeletons**

```toml
[deps.nvim]
command = "nvim"
target = "latest"

[deps.nvim.mac]
installer = "brew"
source = "https://neovim.io/doc/install/"

[deps.nvim.linux]
installer = "official_tarball"
source = "https://neovim.io/doc/install/"
```

```toml
[meta]
generated_at = "2026-05-10T00:00:00Z"
generator_version = "1"
manifest_commit = "unknown"

[deps.nvim]
[deps.nvim.mac]
platform = "mac"
arch = "arm64"
installer = "brew"
version = "0.12.2"
source_url = "https://neovim.io/doc/install/"
checksum = ""
filename = ""
```

- [ ] **Step 2: Update documentation to mention the new root files**

```md
The dependency strategy lives in `deps.toml`.
The frozen dependency state lives in `deps.lock`.
```

- [ ] **Step 3: Run a syntax sanity check on the new files**

Run:

```bash
grep -n "deps.toml\|deps.lock" README.md docs/roadmap.md
```

Expected: both file names appear in the docs.

### Task 2: Teach the installer to read TOML

**Files:**
- Modify: `scripts/install-deps`
- Modify: `Makefile`

- [ ] **Step 1: Replace TSV parsing with TOML parsing**

```bash
deps_file="${DEPS_FILE:-$DOTFILES_PATH/deps.toml}"
lock_file="${LOCK_FILE:-$DOTFILES_PATH/deps.lock}"
```

- [ ] **Step 2: Load tool records from `deps.toml` and platform-specific data**

```bash
python3 - <<'PY'
import tomllib
from pathlib import Path
data = tomllib.loads(Path("deps.toml").read_text())
print(data["deps"]["nvim"]["command"])
PY
```

- [ ] **Step 3: Keep existing `install`, `check`, `list`, and `plan` modes working**

```bash
scripts/install-deps list
scripts/install-deps plan
scripts/install-deps check --only nvim
```

- [ ] **Step 4: Update Makefile targets to point at the new manifest path**

```make
deps:
	bash scripts/install-deps
```

### Task 3: Add lock-aware dependency actions

**Files:**
- Modify: `scripts/install-deps`
- Modify: `Makefile`

- [ ] **Step 1: Read `deps.lock` for tools that must install from frozen artifacts**

```bash
scripts/install-deps check
scripts/install-deps plan
```

- [ ] **Step 2: Make `deps` fail when the current platform is missing a lock entry**

```bash
if missing_lock_entry; then
  die "missing lock entry for $name on $platform/$arch"
fi
```

- [ ] **Step 3: Add `deps-update-lock` support for full and partial refresh**

```make
deps-update-lock:
	bash scripts/install-deps update-lock
```

### Task 4: Refresh docs and verify behavior

**Files:**
- Modify: `README.md`
- Modify: `docs/roadmap.md`

- [ ] **Step 1: Document the new workflow**

```md
make deps
make deps-update-lock
make deps-plan
```

- [ ] **Step 2: Reconcile the roadmap with the TOML manifest and lock-file design**

```md
v0.5 uses deps.toml plus deps.lock.
```

- [ ] **Step 3: Run the project checks**

Run:

```bash
make check
make deps-plan
```

Expected: checks pass and the plan prints the TOML-backed dependency table.