docs(04-01): complete dependency bootstrap plan

2026-04-05 15:15:32 +03:00
parent 0f30c0d156
commit 842cfea268
3 changed files with 422 additions and 9 deletions
--- a/.planning/phases/04-input-sources/04-01-SUMMARY.md
+++ b/.planning/phases/04-input-sources/04-01-SUMMARY.md
@@ -0,0 +1,112 @@
+---
+phase: 04-input-sources
+plan: 01
+subsystem: build-system
+tags: [dependencies, bootstrap, wave-0]
+requires: []
+provides:
+  - go-git/v5 module available for git history traversal
+  - atotto/clipboard module available for cross-platform clipboard
+  - golang.org/x/exp/mmap available for memory-mapped large file reads
+affects:
+  - go.mod
+  - go.sum
+tech-stack:
+  added:
+    - github.com/go-git/go-git/v5 v5.17.2
+    - github.com/atotto/clipboard v0.1.4
+    - golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90
+  patterns: []
+key-files:
+  created: []
+  modified:
+    - go.mod
+    - go.sum
+decisions:
+  - Ran go get + go mod download (not go mod tidy) so unused modules remain pinned until Wave 1 imports them
+  - Accepted `// indirect` markers on all three modules — they will be promoted to direct requires when plans 04-02/04-03/04-04 add imports
+metrics:
+  duration: "~1 min"
+  completed: 2026-04-05
+  tasks_completed: 1
+  files_modified: 2
+---
+
+# Phase 4 Plan 1: Dependency Bootstrap Summary
+
+Added three external Go modules (go-git/v5, atotto/clipboard, x/exp/mmap) that Phase 4 input-source plans require, so Wave 1 parallel work can compile cleanly without dependency resolution thrash.
+
+## Objective
+
+Resolve and record the three external Go dependencies needed for Phase 4 input sources — git history (INPUT-02), clipboard (INPUT-05), and memory-mapped large file reads (CORE-07) — in go.mod/go.sum so downstream plans compile on first attempt.
+
+## What Was Built
+
+### Task 1: Add go-git, clipboard, x/exp/mmap (commit 0f30c0d)
+
+Resolved the three modules via `go get` at `@latest`:
+
+| Module                          | Version                                  | Purpose                              |
+| ------------------------------- | ---------------------------------------- | ------------------------------------ |
+| `github.com/go-git/go-git/v5`   | v5.17.2                                  | Git history traversal (INPUT-02)     |
+| `github.com/atotto/clipboard`   | v0.1.4                                   | Cross-platform clipboard (INPUT-05)  |
+| `golang.org/x/exp`              | v0.0.0-20260312153236-7ab1446f8b90       | `mmap` subpackage for CORE-07        |
+
+Transitive additions pulled in by go-git: `dario.cat/mergo`, `Microsoft/go-winio`, `ProtonMail/go-crypto`, `cloudflare/circl`, `cyphar/filepath-securejoin`, `emirpasic/gods`, `go-git/gcfg`, `go-git/go-billy/v5`, `golang/groupcache`, `jbenet/go-context`, `kevinburke/ssh_config`, `pjbgf/sha1cd`, `sergi/go-diff`, `skeema/knownhosts`, `xanzy/ssh-agent`, `gopkg.in/warnings.v0`.
+
+All three target modules are listed in `go.mod` under the indirect require block; they will be promoted to direct requires automatically by `go mod tidy` when Wave 1 plans add import statements.
+
+## Verification Results
+
+- `go build ./...` — exit 0
+- `go vet ./...` — exit 0
+- `grep -c "go-git/go-git/v5\|atotto/clipboard\|golang.org/x/exp" go.mod` → 3
+- `go.sum` contains checksums for all three modules and their transitive deps
+
+## Deviations from Plan
+
+### [Rule 3 - Blocking] Skipped `go mod tidy`
+
+- **Found during:** Task 1 verification
+- **Issue:** The plan's step sequence ended with `go mod tidy`, but tidy removes modules with no importing source file. Running it erased all three target modules from go.mod entirely (not even indirect), failing the acceptance criteria (`grep "github.com/go-git/go-git/v5" go.mod` returned nothing).
+- **Fix:** Re-added the three modules with `go get`, then ran `go mod download` (which populates go.sum without pruning unused modules) instead of `go mod tidy`. All three modules are now recorded as `// indirect` in go.mod — they will be auto-promoted to direct requires by the first Wave 1 plan that imports them.
+- **Files modified:** go.mod, go.sum
+- **Commit:** 0f30c0d
+- **Rationale:** The plan explicitly stated "If `go mod tidy` moves a module to indirect, that is acceptable only if no source file yet imports it" — so indirect status is an allowed outcome. `go mod download` achieves the same checksum registration while keeping the modules in go.mod.
+
+## Decisions Made
+
+1. **Skip `go mod tidy` for bootstrap commits** — Use `go mod download` instead when adding deps ahead of their consumers, so modules stay pinned in go.mod.
+2. **Accept indirect status** — Wave 1 plans will promote these three modules to direct requires when they add import statements; no manual edit needed now.
+
+## Files Modified
+
+- `go.mod` — 3 target modules + 16 transitive modules added
+- `go.sum` — checksums for all new modules
+
+## Known Stubs
+
+None. This plan only touches module declarations; no source code, no stubs.
+
+## Metrics
+
+| Metric          | Value                          |
+| --------------- | ------------------------------ |
+| Tasks completed | 1/1                            |
+| Commits         | 1 (0f30c0d)                    |
+| Files modified  | 2 (go.mod, go.sum)             |
+| Duration        | ~1 minute                      |
+| Deviations      | 1 (Rule 3 — skip `mod tidy`)   |
+
+## Next Steps
+
+Wave 1 plans (04-02 git source, 04-03 url source, 04-04 clipboard source, plus CORE-07 mmap reader) can now import from these modules without running their own `go get`. `go mod tidy` will naturally promote them to direct requires as their first import lands.
+
+## Self-Check: PASSED
+
+- FOUND: go.mod contains `github.com/go-git/go-git/v5 v5.17.2`
+- FOUND: go.mod contains `github.com/atotto/clipboard v0.1.4`
+- FOUND: go.mod contains `golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90`
+- FOUND: commit 0f30c0d in git log
+- VERIFIED: `go build ./...` exits 0
+- VERIFIED: `go vet ./...` exits 0