Дмитрий
af310ebf7c
- gh 2.92.0 installed via choco (winget absent on Server 2022 Eval) - gh auth already wired via GITHUB_TOKEN env (CoralMinister) - Token scope: contents:read OK, issues/PRs forbidden - Memory workspace bootstrapped for c:/моя/проекты/claude-brain/ Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
256 lines
20 KiB
Markdown
256 lines
20 KiB
Markdown
# 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) |
|
||
|
||
---
|
||
|
||
## 9. Followup (2026-05-11, позже)
|
||
|
||
Короткая follow-up сессия в новом workspace `c:/моя/проекты/claude-brain/`:
|
||
|
||
- **Closed Outstanding #4 (gh CLI install)** — поставлен через `choco install gh -y`, версия `gh 2.92.0` в `/c/Program Files/GitHub CLI/gh.exe`. PATH в текущем bash не подхватился (Bash tool inherited PATH со старта Claude Code до choco install) — вызов абсолютным путём.
|
||
- **gh auth уже работал** через env `GITHUB_TOKEN` как `CoralMinister` (без `gh auth login`).
|
||
- **Token scope ограничен:** `contents:read` ✓, `issues:read`/`pull_requests:read` ✗ (GraphQL "Resource not accessible by personal access token"). Если для будущих задач понадобится Issues/PRs — расширить scope.
|
||
- **winget отсутствует** на Server 2022 Eval (как и предполагалось в outstanding #4 fallback).
|
||
- **Memory bootstrap для brain workspace** в `~/.claude/projects/c--------------claude-brain/memory/`: `MEMORY.md` + 4 entries (user_role, reference_bootstrap_session, project_outstanding_items, reference_environment).
|
||
|
||
**Конец session log.**
|