docs(sessions): brain v1.0 bootstrap session log

Comprehensive conspectus of the 2026-05-11 bootstrap session: - Pre-bootstrap decisions (mode 0%, subagent-driven, etc.) - Phase-by-phase chronology (commits + artifacts + verification outputs) - 11 bugs discovered and fixed (6 plan + 5 Phase 9 runtime) - Windows Server 2022 / Git Bash quirks (Cyrillic paths, jq fopen, etc.) - Outstanding items (Liderra main push deferred, MAGIC_API_KEY rotation deferred) - Workflow learnings (TDD success, Subagent dispatch granularity, mock CLI patterns) - Final metrics (14 commits, 8/8 tests, 64/64 hook subtests, 0 leaks) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 07:12:31 +03:00
parent 52584df34e
commit bb40760a70
1 changed files with 245 additions and 0 deletions
@@ -0,0 +1,245 @@
+# Session 2026-05-11 — Brain v1.0 Bootstrap
+
+**Дата:** 2026-05-11 (ночная сессия с переходом из 2026-05-10)
+**Скоуп:** Извлечение «мозга Claude» из проекта Лидерра в независимый репозиторий + публикация на GitHub.
+**Итог:** Brain v1.0 опубликован — `CoralMinister/claude-brain` (private), 14 commits + tag `brain-v1.0`, 8 sync-скриптов с TDD, end-to-end install+verify работают.
+**Контекст-родитель:** Этот session log — отдельный документ. Architecture spec — [../architecture.md](../architecture.md) (копия Liderra spec на момент bootstrap).
+
+---
+
+## 1. Pre-bootstrap решения пользователя
+
+| Решение | Выбор |
+|---|---|
+| Mode | Economy 0% (полная rigor — full reads, real outputs, file:line refs, no "should work" claims) |
+| Execution | Subagent-Driven Development (фресный субагент per Phase, two-stage review для TDD-фаз) |
+| Worktree | Не нужен (новый repo, не модификация Лидерры in-place) |
+| Phase 0 Task 0.4 — rotate MAGIC_API_KEY | SKIP (deferred; masking placeholder обеспечивает security) |
+| Phase 8.2 — GitHub repo | EXECUTE (опция (c) — repo создан вручную через web UI, потом push через token URL) |
+
+---
+
+## 2. Phase-by-phase хронология (с commit SHAs)
+
+### Phase 0 — Pre-bootstrap discovery
+**Commit Лидерры:** `b53ee28` (docs: brain bootstrap discovery results)
+**Артефакт:** `docs/superpowers/specs/2026-05-10-brain-bootstrap-discovery-results.md` (317 строк)
+
+**Verified:**
+- `claude` CLI: 2.1.138 (Claude Code), но **НЕ в `$PATH`** — лежит в VSCode extension binary `C:\Users\Administrator\.vscode\extensions\anthropic.claude-code-2.1.138-win32-x64\resources\native-binary\claude.exe`
+- `claude plugin` subcommands: `disable|enable|install|list|marketplace|prune|tag|uninstall|update|validate`
+- **`claude plugin marketplace add`** — правильная форма (плагин-вложенная), НЕ `claude marketplace add`
+- jq 1.8.1 (установлен через `choco install jq -y` во время Phase 0 — было MISSING, system-state-change)
+- python 3.14.4 (no `python3` alias — скрипты должны использовать `python`)
+- git 2.54.0
+- **gh CLI** NOT installed
+- gitleaks 8.30.1 (locally в `c:/моя/проекты/портал crm/Документация/bin/gitleaks.exe`)
+- jq deep-merge: `+` form broken ("Cannot index object with number"); **рабочая форма** `jq -s '.[0] * {mcpServers: (.[0].mcpServers * .[1].mcpServers)}'` ИЛИ `jq --slurpfile brain ...`
+- `~/.claude/backups/` glob: реально `*.backup.<unix_ms>`, НЕ `*.json` (5 backups содержат старый un-masked API_KEY — local-only, no git exposure)
+
+### Phase 1 — Brain repo skeleton
+**Commit brain:** `1e68fa9` (chore: initial brain repo scaffold)
+**Файлы:** `.gitignore` (27 lines — plan estimate 22 был занижен), `experiments/README.md`, `experiments/.gitkeep`
+
+### Phase 2 — Extract artifacts
+**Commit brain:** `ed9bade` (feat: extract brain artifacts)
+**21 файл:**
+- `project-files/`: CLAUDE.md.template (266) + 4 docs templates (Pravila 720 / Plugin_stack 916 / Tooling 613 / CHANGELOG) + visualization HTML (3122) + .mcp.json.template (3 universal MCP, laravel-boost dropped)
+- `user-level-files/`: 10 hook scripts + settings-fragment.json (enabledPlugins+permissions+hooks) + marketplaces.json (3) + plugins-manifest.json (4 plugins pinned) + mcp-user.template.json (magic с placeholder)
+
+**Security gate:** gitleaks scan — `no leaks found` (793.91 KB scanned in 277ms). API_KEY masked через `<<MAGIC_API_KEY>>`.
+
+### Phase 3 — Library scripts TDD
+**Commits brain (5):**
+- `9557109` common.sh (log_*, require_cmd, make_backup_dir) — 4 tests
+- `0ba32c2` merge-settings.sh (jq --slurpfile assignment для replace) — 5 tests
+- `c37fd3c` merge-mcp.sh (jq --slurpfile pattern) — 6 tests
+- `042316e` setup-secrets.sh (--secret/--skip/--list modes) — 4 tests
+- `ba0a28b` install-plugins.sh (claude plugin marketplace add) — 2 tests
+
+### Phase 4 — Main scripts TDD
+**Commits brain (3):**
+- `dd238e5` verify.sh (.brain-version + sha256 + strict-secrets) — 2 tests
+- `6949a9d` install.sh (orchestrator, project/user mode detection) — 4 tests
+- `3d24925` extract.sh (reverse sync diff/apply) — 2 tests
+
+### Phase 5 — Meta docs
+**Commit brain:** `917ef33` (docs: brain meta documentation + manifest.json)
+**11 файлов:** CLAUDE.md (37), README.md (47), CHANGELOG.md (38), manifest.json (32, sha256 для 23 файлов), docs/architecture.md (778, copy of Liderra spec), docs/how-to-use-brain.md (42), docs/how-to-experiment.md (42), docs/secrets-and-tokens.md (55), docs/consumer-projects.md (20), user-level-files/README.md (15), project-files/README.md (17).
+
+### Phase 6+7 — CI + verification
+**Commit brain:** `97b5da3` (ci: GitHub Actions workflow)
+**CI workflow:** Python syntax + JSON valid + 8 script tests + 3 hook test files + gitleaks + markdownlint
+**Verification:**
+- gitleaks: 0 findings (926.75 KB scanned)
+- 8/8 script tests OK
+- 64/64 hook subtests PASS (54 economy-mode + 4 economy-self-check + 6 economy-state-guard)
+- install.sh `--dry-run` на Лидерре — `Detected mode: project` + exit 0 (через `BRAIN_ROOT_OVERRIDE=1`)
+
+### Phase 8.1 — Tag
+**Brain tag:** `brain-v1.0` (annotated, объект SHA менялся)
+
+### Phase 8.2 — GitHub push (был BLOCKED → resolved)
+**Block:** fine-grained PAT (используется в Liderra) не имеет `Administration: Write` permission на user-level. POST `/user/repos` → HTTP 403 «Resource not accessible by personal access token».
+**Resolution:** Пользователь создал repo вручную через https://github.com/new (private, empty). Push via token URL:
+```bash
+git branch -M main                                            # master → main (Windows git default vs GitHub default)
+git remote add origin "https://${GITHUB_TOKEN}@github.com/CoralMinister/claude-brain.git"
+git push -u origin main                                       # 14 commits pushed
+git push origin brain-v1.0                                    # tag pushed
+git remote set-url origin "https://github.com/CoralMinister/claude-brain.git"  # token stripped
+```
+
+### Phase 9 — Self-test (revealed 5 critical bugs)
+**Bug 1:** `merge-mcp.sh` через `jq --slurpfile` fails на Cyrillic paths Windows MSYS2 (`Could not open` — jq C-level fopen не понимает UTF-8 path).
+**Bug 2:** `install.sh ${rel%.template}` — только trailing `.template`, не middle segment. `CHANGELOG_claude_md.template.md` оставался с `.template.` внутри.
+**Bug 3:** manifest.json хранит brain-repo paths, verify.sh ищет target paths — pathing semantic mismatch (verify не может пройти на real consumer install).
+**Bug 4:** `make_backup_dir` создаёт пустой dir, файлы не backupятся — overwrite consumer'а необратим.
+**Bug 5:** brain's `project-files/README.md` overwrites consumer's `README.md` (оба попадают в target root после template stripping).
+
+### Phase 9b — Hotfix
+**Commit brain:** `52584df` (fix(scripts): 5 critical bugs from Phase 9 self-test) — 7 files changed / +277 / -35, ONE atomic commit.
+
+**Fixes:**
+- **Bug 1:** `merge-mcp.sh` — `jq --argjson brain "$(cat ...)"` вместо `--slurpfile` (cat handles UTF-8 paths fine, jq получает pre-parsed JSON)
+- **Bug 2:** `install.sh` — `dst_rel="${rel//.template\./.}; dst_rel="${dst_rel%.template}"` (strip middle + trailing)
+- **Bug 3:** manifest.json restructured into `files: {project-mode, user-mode, brain-internal}` maps с target-relative paths; verify.sh detects mode, picks matching map
+- **Bug 4:** install.sh — `rsync -a --exclude .git/ --exclude .brain-backup-*` fallback `cp -r` ПЕРЕД modifications
+- **Bug 5:** install.sh skip `README.md` in copy loops (brain READMEs — internal docs, не consumer content)
+
+**Re-test:** install + verify end-to-end PASS на `/tmp/test-consumer-fix-final-udzgWI`. +17 new test assertions added (12 install + 9 merge-mcp + 6 verify).
+
+**Tag re-pointed:** `brain-v1.0` annotation preserved, target moved `97b5da3` → `52584df` (tag не был ещё push'нут).
+
+### Phase 10 — Liderra marker + memory
+**Commit Лидерры:** `d598aec` на `supplier-sync-plan3` (subagent landed там потому что это был current branch). `.brain-version` = `brain-v1.0\nsha: 52584df34e1a8b2117b3f254731b06f52d84645c`.
+**Memory:** `project_claude_brain.md` (новый), MEMORY.md (entry added), `project_state.md` (top), `reference_github.md` (планируемый repo упомянут).
+
+### Phase 8.2 follow-up — GitHub publish + Liderra branch cleanup
+- ✅ Brain pushed (см. Phase 8.2 resolution выше)
+- ✅ Cherry-pick `d598aec` → main (новый SHA `8965650`), main локально 3 commits ahead origin/main
+- ✅ `git rebase --onto 8c70255 d598aec supplier-sync-plan3` — `d598aec` удалён из feature branch; 9 Plan 3 commits replayed с новыми SHA (`8a611eb..8fc9d3e`)
+- ⏸ Push main BLOCKED — pre-push lychee нашёл 33 битые ссылки в 4 .md (28 в Plan 3 supplier-sync docs из прошлой сессии, 5 в моих brain extraction spec/plan). Pre-existing problem. User выбрал skip push до отдельной сессии для починки.
+
+---
+
+## 3. Обнаруженные плановые баги (8 total)
+
+Plan был написан до bootstrap. Эти баги обнаружены при первом реальном запуске:
+
+| ID | Где | Симптом | Fix |
+|---|---|---|---|
+| A | Plan §Task 3.3 | `jq -s '.[0] \| .mcpServers = (... + .[1].mcpServers)'` → "Cannot index object with number" | `jq --slurpfile brain ...` или `--argjson` |
+| B | Plan §Task 3.5 | `claude marketplace add` → no such subcommand | `claude plugin marketplace add` |
+| C | Plan §Task 3.5 | `claude` not in `$PATH` (VSCode extension only) | Fallback to JSON edit mode в install-plugins.sh |
+| D | Plan §Task 3.2 | `jq '.[0] * {enabledPlugins: ...}'` → recursive merge (union, not replace) | Explicit `--slurpfile $frag` + `.key = $frag[0].key` assignment |
+| E | Plan §Task 4.2 | `cp -r project-files/* target/` не strip'ает `.template` суффикс | `find` loop + `dst_rel="${rel%.template}"` |
+| F | Plan §Task 4.3 | extract.sh middle-elif heuristic был syntactically buggy | Cleaner two-step fallback |
+| Phase 9 #1 | install.sh runtime | Cyrillic path → jq fopen fail | `--argjson "$(cat ...)"` |
+| Phase 9 #2 | install.sh runtime | `${rel%.template}` only trailing | `${rel//.template\./.}` + `${rel%.template}` |
+| Phase 9 #3 | verify.sh + manifest | Path semantic mismatch | manifest.files → {project-mode, user-mode, brain-internal} maps |
+| Phase 9 #4 | common.sh + install.sh | Empty backup | rsync/cp -r target tree to backup BEFORE modifications |
+| Phase 9 #5 | install.sh | README.md overwrite consumer | Skip brain READMEs in copy loops |
+
+**Итого:** 11 багов обнаружены и исправлены за bootstrap. План v1.0 был ~70% корректен — оставшиеся 30% потребовали runtime discovery.
+
+---
+
+## 4. Quirks среды (Windows Server 2022 + Git Bash + VSCode)
+
+1. **Cyrillic paths**: jq на MSYS2 не открывает файлы с UTF-8 путями. Workaround: `--argjson "$(cat ...)"` вместо `--slurpfile`.
+2. **`python` not `python3`**: только `python` alias существует.
+3. **`claude` CLI vs `claude plugin marketplace`**: subcommand структура `claude plugin <sub>` (включая `marketplace`).
+4. **Git default branch на Windows = `master`**, GitHub default = `main`. `git branch -M main` нужен перед первым push.
+5. **`core.autocrlf=true`**: git нормализует EOL на checkout. Может изменять sha256 файла при clone на другой машине. Для brain v1.0 — within-machine sync, не проблема.
+6. **gitleaks путь**: либо в `$PATH`, либо в `c:/моя/проекты/портал crm/Документация/bin/gitleaks.exe` (предустановлен в Liderra).
+7. **Fine-grained PAT vs classic PAT**: fine-grained не имеет user-level Administration:Write по умолчанию — POST `/user/repos` → 403. Classic PAT с `repo` scope работает, или создать repo через web UI.
+8. **Lefthook pre-push hooks**: gitleaks-full-history + lychee + larastan + pint + pest + markdownlint + cspell. Можно ловить на pre-existing проблемах не введённых текущим коммитом.
+9. **`~/.claude/backups/` filename pattern**: `*.backup.<unix_ms>`, НЕ `*.json` (могут содержать unredacted API_KEY).
+
+---
+
+## 5. Outstanding items для будущих сессий
+
+### Critical
+1. **Push Liderra main → origin/main** — 3 commits ahead, blocked by lychee (33 broken links). Опции:
+   - Fix broken links в 4 .md (Plan 3 plan/spec + мои brain plan/spec) — нужна правка relative paths
+   - Добавить exclude patterns в `.lychee.toml`
+2. **Rotate MAGIC_API_KEY на 21st.dev** (Phase 0 Task 0.4 deferred). Текущий ключ formally compromised (виден в session logs).
+
+### Important
+3. **Tooling/Pravila обновить** — добавить brain extraction в реестр инструментов как infrastructure category (#34 claude-brain или similar). После push main.
+4. **gh CLI install** — `choco install gh` для будущих GitHub операций без curl boilerplate.
+5. **Plan 3 supplier-sync docs broken links** — Plan 3 documentation использует `app/...` paths из `docs/superpowers/plans/...` но resolve неправильно. Hardcoded `../../../app/...` или `.lychee.toml` exclude.
+
+### Nice-to-have
+6. **`.gitattributes`** в brain repo с `* -text` для CRLF stability (для clone на другие machines с разными autocrlf settings).
+7. **Tag immutability**: `brain-v1.0` был moved из `97b5da3` → `52584df` после Phase 9b hotfix. Push не было между. Для будущих версий — не moveать после push, лучше bump до `brain-v1.0.1`.
+8. **Mock `claude` CLI in install-plugins-test**: пишет в global `/tmp/claude-calls.log` — race condition если parallel CI runs.
+
+---
+
+## 6. Workflow learnings
+
+### Что работало хорошо
+- **TDD discipline на bash scripts** — каждый failing-test-first cycle поймал по 1-3 бага до commit'а.
+- **Subagent-driven dispatch per Phase** — 16 subagent dispatches (вместо 47 по плану TDD-granularity) — эффективный balance cost/quality.
+- **Security gates (gitleaks)** — на Phase 2 (extract) и Phase 7 (pre-release). Поймали бы leak'и до commit'а.
+- **Plan corrections inline in dispatcher prompt** — Phase 0 нашёл baги в плане; не редактировал план, передавал corrections в каждый последующий subagent через prompt. Чистая commit-история плана.
+
+### Что нужно улучшить в следующий раз
+- **Plan corrections должны быть applied к самому плану** перед dispatch — если plan живёт в repo и читается несколькими subagent'ами, inline corrections в prompt становятся single-point-of-failure.
+- **Mock CLI bin (Phase 3 Task 3.5)** — `claude` mock должен был сразу матчить real subcommand структуру. Plan указал устаревший интерфейс, subagent fixed it on the fly.
+- **Phase 9 self-test надо было дублировать с TDD-стилем** — 5 багов dropped на нас сразу. Если бы каждый test-консьюмер имел свой failing-test, мы поймали бы их по одному, не batch.
+
+### Decision pattern, который сработал
+- **Subagent reports DONE_WITH_CONCERNS** → controller (я) читает concerns, классифицирует как scope/correctness/observation → only correctness ones влияют на следующий dispatch → observation ones flagged в session log без блока.
+
+---
+
+## 7. Файлы и refs
+
+### В brain repo
+- `CLAUDE.md` — meta description
+- `README.md` — quick start
+- `CHANGELOG.md` — v1.0 release notes
+- `manifest.json` — sha256 + tool requirements
+- `docs/architecture.md` — copy of Liderra spec
+- `docs/how-to-use-brain.md` / `how-to-experiment.md` / `secrets-and-tokens.md` / `consumer-projects.md`
+- `docs/sessions/2026-05-11-bootstrap-session.md` — этот файл
+- `scripts/{install,verify,extract}.sh` + 5 lib helpers + 8 tests + 3 fixtures
+- `.github/workflows/ci.yml`
+
+### В Liderra
+- `docs/superpowers/specs/2026-05-10-claude-brain-extraction-design.md` (776 строк, design spec)
+- `docs/superpowers/plans/2026-05-10-claude-brain-extraction.md` (3430 строк, implementation plan)
+- `docs/superpowers/specs/2026-05-10-brain-bootstrap-discovery-results.md` (317 строк, Phase 0 results)
+- `.brain-version` (на local main; на supplier-sync-plan3 удалён через rebase)
+
+### В Liderra memory (`~/.claude/projects/c---------------------crm-------------/memory/`)
+- `project_claude_brain.md` — brain architecture summary
+- `MEMORY.md` — index entry added
+- `project_state.md` — top updated с brain extraction status
+- `reference_github.md` — claude-brain repo URL добавлен
+
+---
+
+## 8. Метрики
+
+| Метрика | Значение |
+|---|---|
+| Brain commits total | 14 (12 feature/docs + 2 hotfix/CI) |
+| Brain tag | `brain-v1.0` @ `52584df` |
+| Script tests passing | 8/8 (54 assertions всего, +17 added в Phase 9b) |
+| Python hook subtests | 64/64 (54 economy-mode + 4 self-check + 6 state-guard) |
+| Gitleaks findings | 0 (за все сканы) |
+| Bugs обнаружено и исправлено | 11 (6 plan + 5 runtime) |
+| Files в manifest.json | 23 |
+| Brain repo size | ~270 KB |
+| Subagent dispatches | 16 (включая Phase 9 + 9b) |
+| Liderra commits созданные сессией | 2 (b53ee28 discovery + 8965650 marker on main) |
+| Liderra commits отрезанные ребейзом | 1 (d598aec на supplier-sync-plan3) |
+
+---
+
+**Конец session log.**