Skip to content

AGENTS.md

Latest commit

 

History

History
541 lines (436 loc) · 39.2 KB

AGENTS.md

File metadata and controls

541 lines (436 loc) · 39.2 KB
Raw

Project Agent Rules — MSCodeBase Hybrid Architecture (65 Registered Tools)

Global system prompt / context injection for the AI Agent in Zed IDE. Applied across all projects. Optimized for the hybrid model: 16 Intel Layer + 32 Core MCP (включая codebase hub + 6 LSP + predict_change + bootstrap_pipeline) + 13 Inline/Diagnostic + 4 Dev Tools = 65 registered (+1 execute_script при MSCODEBASE_EXECUTE_SCRIPT_ENABLED=true → 66)

* execute_script отключён по умолчанию. Включить: MSCODEBASE_EXECUTE_SCRIPT_ENABLED=true в .env.

0. FIRST STEP IN ANY SESSION

  1. Check File-Contract: Артефакты MCP живут ВНЕ проекта (Задача 4/5). progress.json — в системной папке: <MSCODEBASE_DATA_DIR | %LOCALAPPDATA%/mscodebase | ~/.cache/mscodebase>/projects/<hash8>/progress.json, где <hash8> = md5(normalized project path)[:8] (lower, \\→/). Быстрый способ узнать путь — intel_get_runtime_status (поле progress_file) или python -c "from src.core.artifact_paths import get_progress_file; print(get_progress_file(Path('.').resolve()))". Легаси-путь .mscodebase/progress.json в проекте — больше не пишется.

  2. Read the Diary + Wisdom: Review the first 5 entries in AGENT_DIARY.md and read WISDOM.md целиком (если существуют) — WISDOM.md загружается всегда, это дистиллят фактов, а не архив.

  3. Determine MCP Context:

    • If intel_* tools or search_code are available → MCP-FIRST MODE (§0.2). IDE grep/read — только fallback.
    • If absent → MCP server offline. Work exclusively with grep, read_file, terminal.

  4. Runtime Check (MCP pipe): Call debug_runtime_passport() — единственная команда проверки «жив ли MCP-процесс».

    • Ответ с RUN_ID / BUILD_ID / PID → MCP подключён, продолжаем.
    • Transport error / «Not connected» → MCP offline, fallback на grep.
    • НЕ использовать intel_get_runtime_status для проверки связи — он проверяет embedder/индекс, а не pipe.

  5. Load Project Memory: Call intel_get_project_memory() to learn ADRs, known issues, tech debt.

  6. ⚠️ MULTI-WINDOW CHECK: intel_get_runtime_status().project_path — ЭТОТ проект видит MCP. Если пользователь говорит о ДРУГОМ проекте (лежит рядом, открыт в другом окне) — НЕ ДОВЕРЯЙ данным get_index_status() для этого проекта. Вместо этого:

    • Проверь, открыт ли проект: ls <путь>
    • Предупреди пользователя: «Сейчас MCP показывает проект X. Хотите, переключусь на Y?»
    • Используй intel_explain_project_state для проверки другого проекта

0.1. MCP TOOL CALL PROTOCOL (MANDATORY)

Полный справочник инструментов с JSON Raw Input — источник правды в коде: src/mcp/server_tools.py (class-based) + src/mcp/tools/ + src/core/intelligence/tools_reg.py (intel_*).

Формат вызова: JSON Raw Input (Zed MCP)

Каждый tool call = имя инструмента + JSON-тело (Raw Input). Это не shell, не Python, не func().

Tool:   search_code
Raw Input:
{
  "query": "ETA estimated_seconds reindex job progress",
  "mode": "fast"
}

Без аргументов → пустой объект {}:

Tool:   debug_runtime_passport
Raw Input: {}

Tool:   intel_trigger_reindex
Raw Input: {}
  1. Один tool + один JSON за раз — отдельный JSON-RPC запрос.
  2. Запрещено склеивать в одну строку или один Raw Input несколько инструментов.
  3. Запрещено 3+ MCP параллельно — таймауты. Строго последовательно.
  4. Порядок сессии (Raw Input):
# Tool Raw Input
1 debug_runtime_passport {}
2 intel_get_runtime_status {}
3 intel_get_project_memory {}
4 intel_explain_project_state {}
  1. Источник правды: src/mcp/server.py + src/core/intelligence/layer.py.
  2. После ошибки — не retry с теми же JSON. Сначала debug_runtime_passport {}, потом альтернатива.

Reindex (Raw Input):

Tool: intel_trigger_reindex     Raw Input: {}
      → ответ: job_id

Tool: intel_get_job_status      Raw Input: { "job_id": "24fc56ed" }

Tool: search_code               Raw Input: { "query": "...", "mode": "quality" }

0.2. MCP-FIRST MODE (MANDATORY when MCP online)

Если intel_get_runtime_status ответил без transport error → работай ТОЛЬКО через MCP. Не используй grep, read_file, Glob, Shell для исследования кода, пока MCP жив.

Замена IDE-инструментов на MCP

Задача ❌ Не использовать ✅ MCP
Найти код по смыслу grep search_code(mode="quality")
Точное имя файла/символа grep search_code(mode="fast")
Архитектура / связи читать файлы intel_code_topology, impact_analysis
Символ: кто вызывает grep get_symbol_info
Прочитать файл read_file read_live_file
Состояние проекта shell / cat intel_explain_project_state
Полный снэпшот 5+ вызовов intel_get_project_context
Индекс / chunks — codebase(action="index", path="status")
Логи / ошибки cat terminal get_logs, intel_predict_root_cause
Здоровье системы — get_health_report, debug_runtime_passport
Git история git log codebase(action="git", path="log"), codebase(action="git", path="history")
Рисковые файлы — intel_get_hotspots
Data flow переменной grep graph_query(action="flow", name=...)
AST-паттерн grep structural_search
После правки кода — notify_change → codebase(action="index", path="status")

Когда fallback на IDE разрешён

Условие Fallback
MCP transport error / timeout grep + read (≤50 строк)
total_chunks == 0 intel_trigger_reindex → grep до completed
Редактирование файлов Write/StrReplace в IDE (MCP не пишет за агента Cursor)
pytest / install.py / git commit Shell (операции среды, не поиск)
2 подряд одинаковых MCP-fail pivot на grep

Zed 1.14+ sandboxing (2026-08): terminal/fetch — сетевые хосты требуют per-host одобрения. При fallback на fetch (исследование §1.7) отказ «host not granted» — это песочница, не сбой: запросить одобрение хоста у пользователя. MCP-first режим это обходит (context server, не agent-тул) — ещё одна причина не покидать MCP-first без нужды.

Запрещено при живом MCP

  • ❌ grep вместо search_code (если chunks > 0)
  • ❌ Read целых файлов вместо read_live_file / get_symbol_info
  • ❌ Glob для поиска символов вместо search_code(mode="fast")
  • ❌ Shell: git log вместо codebase(action="git", path="log")
  • ❌ Угадывать номера строк — сначала MCP, потом read точечно

Демонстрация правильной сессии (только MCP)

intel_get_runtime_status()
intel_get_project_memory()
intel_explain_project_state()
search_code(query="watchdog heartbeat", mode="quality")
get_symbol_info(query="watchdog_status")
read_live_file(file_path="src\\core\\indexer.py")   ← только нужные строки через MCP

0.5. WORKFLOW: ИСХОДНИКИ → РАСШИРЕНИЕ ZED

Архитектура

  • Source code: <repo-root> — здесь ты редактируешь код.
  • Extension dir: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence — откуда MCP реально запускается.
  • Venv: {EXT}\venv\Scripts\python.exe — Python со всеми пакетами.
  • llama binary: {EXT}\llama_msvc\ (CPU) или {EXT}\llama_vulkan\ (GPU).
  • Models: {EXT}\models\ — GGUF файлы.
  • install.py (из папки проекта) копирует файлы из исходников в расширение.

Стандартный цикл разработки

Когда пользователь просит что-то изменить и проверить:

ШАГ 1 — Правим код в исходниках (<repo-root>\src\)
ШАГ 2 — Синхронизируем в расширение + убиваем процессы
ШАГ 3 — Запускаем install.py для обновления
ШАГ 4 — Запускаем MCP вручную из расширения
ШАГ 5 — Тестируем (search_code, embed, rerank)
ШАГ 6 — Убиваем процессы
ШАГ 7 — Говорим пользователю: «Перезагрузи Zed»

Детальный протокол

Шаг 1 — Правка кода:

  • Редактируешь файлы в <repo-root>\src\.
  • После edit_file / write_file → notify_change().
  • Для переименования файлов используй apply_file_move(old, new) вместо notify_change — мета-патчинг (50ms, 0MB RAM) вместо полной переиндексации (5s, 700MB RAM).

Шаг 2 — Синхронизация + очистка:

# Убить старые процессы
taskkill //F //IM "llama-server.exe" 2>&1 | tail -1
taskkill //F //FI "WINDOWTITLE eq mscodebase*" //IM python.exe 2>&1 | tail -1
sleep 2

# Скопировать изменённые файлы в расширение
# (если install.py запускать не надо, а надо быстро обновить один файл)
cp /path/to/repo/src/providers/reranker/llama_runner.py \
   "/path/to/LocalAppData/Zed/extensions/mscodebase-intelligence/src/providers/reranker/llama_runner.py"

Шаг 3 — install.py (если нужно обновить бинарники/модули):

cd /path/to/repo && python install.py

Учти: install.py интерактивный (спрашивает Y/n). Если нужно авто-подтверждение:

printf 's\nn\n' | python install.py   # s=skip pip, n=skip ONNX models

Шаг 4 — Запуск MCP для теста:

cd "/path/to/LocalAppData/Zed/extensions/mscodebase-intelligence" && \
  nohup venv/Scripts/python.exe -m src.main > /tmp/mcp_test.log 2>&1 &
sleep 8   # ждём пока стартанёт embedder + reranker

Проверить что процессы поднялись:

tasklist //FI "IMAGENAME eq llama-server.exe" //NH 2>&1
/c/Windows/System32/netstat.exe -ano 2>&1 | grep -E ":8080 |:8081 " | grep LISTEN

Шаг 5 — Тестирование:

import httpx
# Embedder
r = httpx.post('http://127.0.0.1:8080/v1/embeddings',
    json={'input': ['Тест']}, timeout=10)
print('Embed:', r.status_code, 'dim=', len(r.json()['data'][0]['embedding']))

# Reranker
r = httpx.post('http://127.0.0.1:8081/rerank',
    json={'query': 'test', 'texts': ['a', 'b']}, timeout=10)
print('Rerank:', r.status_code)

# MCP tools (если MCP запущен — они должны отвечать)
# Используй search_code, intel_get_runtime_status и т.д.

Шаг 6 — Убить тестовые процессы:

taskkill //F //IM "llama-server.exe" 2>&1
taskkill //F //FI "WINDOWTITLE eq mscodebase*" //IM python.exe 2>&1

Шаг 7 — Сообщить пользователю:

«Готово. Перезагрузи Zed — изменения применятся.»

Важные замечания

  • venvlauncher.exe — НЕ зомби. Python 3.13+ на Windows использует venvlauncher/venvwlauncher как bootstrap-процесс (venv/Scripts/python.exe → venvlauncher → python.exe): при проверке tasklist | grep python можно увидеть 2 процесса на один MCP-сервер (основной + venvlauncher-обёртка). Это НОРМАЛЬНОЕ поведение, а не зомби/дубль — не тратить время на диагностику и не убивать (см. инцидент 2026-08-02: PID 21616 ошибочно принят за зомби).

  • install.py шаг 4 (step_copy) копирует llama_msvc/, llama_vulkan/, models/ ТОЛЬКО если их нет в skip. Там они уже есть в skip, так что install.py не затрёт бинарники — только код.

  • llama_runner.py содержит _start_sync() с авто-восстановлением: если CPU DLL пропали — сам скачает и пропатчит. Это страховка на случай если расширение сбросилось при перезагрузке Zed.

  • Vulkan детекция работает автоматически: если есть GPU с Vulkan и llama_vulkan/ с бинарником — MCP использует GPU, иначе CPU.

  • Все тесты проводи в терминале (GitBash), пути в POSIX формате (src/core/...).

0.6. СТРУКТУРА КОРНЯ (cleanup 2026-08-04)

Канонический набор файлов в корне проекта:

  • Код и конфиг: src/, tests/, scripts/, tools/, docs/, experiments/, ruff.toml
  • Правила проекта: AGENTS.md, AGENT_DIARY.md, KNOWN_ISSUES.md, EXPERIMENTS_LOG.md, WISDOM.md (дистиллят ≤50 строк, пополняется по Триггеру 7 §1.19), ISSUE.md (активный аудит-трекер)
  • Установка: install.py / install.bat / install.sh / uninstall.bat, extension.toml, __mscodebase_ext__.marker, start_server.bat
  • Пакет: pyproject.toml, requirements.txt, requirements-lock.txt, MANIFEST.in, LICENSE, README.md, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, AI_INSTALLATION_PROMPT.md
  • Архивы: docs/archive/ (например DEV_DIARY_2026_07.md); DEV_DIARY.md в корне — заглушка-редирект на AGENT_DIARY.md

Запрещено добавлять в корень (см. §6):

  • ❌ Одноразовые тест-скрипты / pytest-обёртки с захардкоженными путями → scripts/ или experiments/, либо удалять
  • ❌ Логи, выводы тестов (*.log, test_output.txt, install_output.txt) — уже в .gitignore, не коммитить
  • ❌ Файлы вне списка выше без явной причины — корень чистился 2026-08-04, не дай ему захламиться заново

1. TOOL SELECTION

1.1 Architectural Substitution Rules

Instead of Use
codebase(action="index", path="status") intel_get_runtime_status
codebase(action="index", path="project_dir") (blocking) intel_trigger_reindex (fire-and-forget)
Multiple low-level calls intel_get_project_context (one snapshot)
Parsing raw logs intel_predict_root_cause or intel_analyze_incident

1.2 Search Code Mode Matrix

search_code(query, mode="auto") is the ONLY search tool. smart_search, deep_search, context_search are DEPRECATED.

Mode When Speed
"fast" Exact file/variable name lookup ~300ms
"quality" Logic, architecture, relationships (default) ~1200ms
"deep" Complex architectural investigation ~2-5s
"context" Find similar code by code fragment ~500ms
"auto" Auto-detect: simple→fast, complex→agentic ~300ms-2s

1.3 Priority Matrix

[ANALYSIS / BRAIN]                  [SURGICAL ACTION]               [FALLBACK]
High-Level Intel Tools              Low-Level Core MCP              Built-in IDE
──────────────────────              ──────────────────────          ───────────
intel_get_runtime_status      ──>   codebase(action="index", path="status")   grep (exact)
intel_trigger_reindex         ──>   notify_change                  grep (fallback)
intel_code_topology           ──>   get_symbol_info / structural   grep
intel_predict_root_cause      ──>   get_logs / get_health_report   terminal cat
intel_get_project_memory      ──>   codebase(action="git", path="log") / codebase(action="git", path="history") (no analog)
intel_get_project_context     ──>   (aggregates 5+ calls)

2. AVAILABLE TOOLS (65)

Полный справочник (аргументы, когда вызывать, anti-patterns): источник правды — src/mcp/server_tools.py + src/mcp/tools/ + src/core/intelligence/tools_reg.py. Актуальное число зарегистрированных инструментов — в логе MCP при старте (📐 MCP Tools: N/M видимы).

A. Intel Intelligence Layer (16 tools)

intel_get_runtime_status, intel_trigger_reindex, intel_reset_index, intel_get_job_status, intel_auto_collect_adrs, intel_code_topology, intel_log_incident, intel_analyze_incident, intel_add_memory_node, intel_get_project_memory, intel_predict_root_cause, intel_get_hotspots, intel_get_telemetry, intel_retract_memory_node, intel_restore_memory_node, intel_supersede_memory_node.

Inline/Diagnostic (13): debug_runtime_passport, intel_get_project_context, intel_explain_project_state, get_runtime_counters, intel_tool_health, intel_execution_timeline, refresh_db_connection, notify_change, read_live_file, get_logs, get_health_report, dual_arm_health_check, ack_impact.

B. Core MCP & Search (32 tools)

v3.2.0 Data Flow: PropertyGraph содержит ASSIGNED_FROM-рёбра, отслеживающие присваивания переменных между телами функций. Трассировка переменной — graph_query(action="flow", name="x") (scope-resolution). Расширенный запрос — graph_query(action="cypher", query="..."). Рёбра имеют опциональное свойство condition_path — список control-flow контекстов вида ["if_statement", "for_statement"]. Поддержка: Python, Rust, Go, JavaScript, TypeScript/TSX, Java, C#, Ruby, PHP, Kotlin, Swift, C, C++, Scala, Dart.

search_code(mode=fast|quality|deep|context|auto), get_symbol_info, impact_analysis, lsp_find_references(file_path, line, col), lsp_find_definition(file_path, line, col), lsp_document_symbols(file_path), lsp_get_type_info(file_path, line, col), lsp_get_diagnostics(file_path), lsp_get_code_actions(file_path, line, col), codebase(action=...), structural_search, graph_query(action=query|cypher|related|flow), submit_background_task, stale_detector.

Hidden core tools (default allowlist): core tool classes that are not in the default MSCODEBASE_MCP_TOOLS allowlist are not exposed to the MCP client (calling them returns tool not found) until added to the allowlist. Examples: get_repo_map, get_repo_rank, get_hotspots, get_bug_correlation, detect_communities, cross_repo_search, cross_project_deps, find_duplicates, generate_chunk_summaries, scan_changes, find_similar_bugs, get_context, bootstrap_pipeline. (Intel / inline / dev tools are always registered and visible.)

Hub-маршруты codebase(action=...) (не отдельные MCP-тулы): codebase(action="index", path=status|progress|health|timeline|project_dir) — индекс; codebase(action="git", path=log|history|branch) — git; codebase(action="rename"|"move"|"safe_delete"|"replace"|"insert_before"|"insert_after") — write. notify_change, read_live_file, get_logs, get_health_report — inline (секция A).

Deprecated (use search_code): smart_search, deep_search, context_search.

v3.2.0 Scope Resolution: data flow запросы — graph_query(action="flow", name=...). Протокол:

  1. graph_query(action="flow", name="result") без scope_id — увидеть ВСЕ result-переменные с контекстом.
  2. Если результатов несколько — выбрать нужный scope_id (кодирует file + function + line).
  3. graph_query(action="flow", name="result", scope_id="...") — точный data flow.
  4. condition_path на рёбрах — пустой список = безусловный, ["if_statement"] = внутри IF.

C. Write Operations — через codebase(action=...) (hub)

codebase(action="rename", old, new, apply) — rename symbol across all files codebase(action="move", symbol, to_file, apply) — move symbol to another file codebase(action="safe_delete", symbol, force, apply) — safe delete with reference check codebase(action="replace", symbol, new_code, apply) — replace function/class body codebase(action="insert_before", anchor, new_code, apply) — insert code before anchor symbol codebase(action="insert_after", anchor, new_code, apply) — insert code after anchor's body ack_impact(file_path) — отдельный inline-тул: подтверждение impact для modification guard

3. STATE AWARENESS

  • If index status (codebase(action="index", path="status")) returns 0 chunks → FORBIDDEN to use search_code. Switch to grep/regex.
  • If chunks > 0 → use search_code for semantic, get_symbol_info for exact names.
  • If using write tools, call ack_impact(file_path) before destructive operations on load-bearing files.

4. MEMORY PROTOCOL

  1. Start: Call intel_get_project_memory(). Study ADRs, known issues, past attempts.
  2. After task: Call intel_log_incident() with component, symptom, root_cause, fix, success.
  3. If you notice an anti-pattern: Call intel_add_memory_node(section="tech_debt", data_json=...).

5. EXECUTION CONTRACT

Reconnaissance

  • NEVER guess line numbers. Use get_symbol_info or grep before read_file.
  • CONTEXT BUDGET: Max 50 lines per read_file call. NEVER ingest entire files.
  • SAFE WRITING: Read target lines before edit. Preserve indentation and style.

Post-Modification

After edit_file / write_file → notify_change(file_path=...) → codebase(action="index", path="status"). Use batch notify: notify_change(file_path=["src/a.py", "src/b.py"]). For file renames, use apply_file_move(old, new) instead of notify_change — it does meta-patching in 50ms instead of full reindex (5s).

Error Handling

  • Do not retry same tool with same params. Pivot to alternative.
  • If MCP fails → grep/cat → find_path → terminal.
  • After failed hypothesis twice → STOP. Pivot to different hypothesis.

Windows Paths

  • MCP tools: Windows escaped format (src\\core\\config.py).
  • Terminal (GitBash): POSIX format (src/core/config.py).

6. ABSOLUTE FORBIDDENS

Deprecated

  • smart_search, deep_search, context_search — DEPRECATED. Use search_code(mode=...).
  • codebase(action="index", path="project_dir") (blocking) — Use intel_trigger_reindex (async).

Architecture

  • Tools must NOT call Registry, Bridge, or Passport directly. Use RuntimeCoordinator.can_execute() + ProjectContext.capture().
  • RuntimeCoordinator must NOT know about Search, Indexer, or Memory.
  • New components must answer: "Which existing layer does it extend?"
  • One class = one responsibility.

Environment

  • NO Docker, NO WSL, NO pytz (use zoneinfo).
  • NO stubs, TODOs, or placeholders. Every change = production-ready.
  • NO debug prints to stdout (breaks JSON-RPC parser).
  • NO investigating a hypothesis after two consecutive observations confirm the same fact.

Repository hygiene (§0.6)

  • NO one-off test scripts / pytest wrappers / logs / test outputs in project root → scripts/ or experiments/, добавить в .gitignore.
  • NO new root files вне канонического набора §0.6.
  • NO второй дневник / KNOWN_ISSUES — AGENT_DIARY.md и корневой KNOWN_ISSUES.md единственные (проверка find . -iname "KNOWN_ISSUES.md").

Чужие данные в репозитории (§7.1a) — ЗАПРЕЩЕНО

Репозиторий PUBLIC (MIT). Поэтому «взять и закоммитить» = опубликовать навсегда.

  • NEVER коммитить выгрузку чужой публикации/страницы/профиля: личные email третьих лиц, блоки Location/Joined/Education, дословный чужой текст целиком.
  • В репозитории допустимы: свой вывод, sha256, URL источника, короткие цитаты по делу.
  • Вне репозитория (сюда): %LOCALAPPDATA%/mscodebase/audit-cache/<задача>/ — сырьё, frozen-входы, полные дампы. Это та же конвенция, что progress.json (§0).
  • Лицензия: наш репозиторий MIT; дословная копия чужого текста (dev.to по умолчанию CC BY-NC-SA) притащит NC/share-alive в наш файл — это заражение лицензии, не только приватность.
  • Gate: scripts/check_third_party_data.py (10-й pre-commit, --selftest = positive 2/2 + negative 2/2, --all = FP-замер). Правила: R1 личный email · R2 сигнатура выгруженного профиля · R3 объёмный чужой дамп (advisory). Вендоренные метаданные зависимостей (fixtures/, lock-файлы, pyproject.toml, package.json, pom.xml) — легитимная атрибуция, в allowlist.
  • Ловушка при написании своего сканера: наивный email-regex даёт 89% мусора (модуль@символ.py в трейсах, n@mcp.tool в сниппетах). Замер 2026-10-03: 767 совпадений на 1893 файлах, из них 686 ложных. Сканер без замера FP бесполезен и умирает от FP-усталости.
  • Перед коммитом: git diff --cached --name-only и спроси себя «это моё или я это выгрузил?».

Параллельные агент-сессии (§7.1b) — обязательный порядок

Инцидент 2026-10-03: две сессии в одном дереве. Одна создала tools/verification/*.py, другая не знала. tools/knowledge/ появился в общем дереве и исчез — сессия объявила «данные потеряны, P1», пока вторая держала их в своём worktree. Третья переключила ветку в чужом дереве. Три инцидента из-за одного нарушения: нет границы территорий.

  1. Одно рабочее дерево = одна сессия = одна задача. Если рядом работает другая сессия — ей нужен свой worktree: git worktree add ../wt-<задача> -b feat/<задача>. Никогда две сессии в одном дереве.
  2. Ветка = территория. Не переключать ветку в дереве, где работает кто-то ещё, и не делать checkout файлов из чужого дерева.
  3. Реестры принадлежат одной сессии. Кто начал писать AGENT_DIARY.md / KNOWN_ISSUES.md / EXPERIMENTS_LOG.md / WISDOM.md / ISSUE.md — тот и владеет ими. Остальные пишут предложение в experiments/<задача>/PENDING_LEDGER.md, а не в реестр. Молчаливый двойной дневник хуже, чем отсутствие записи.
  4. Коммитить только свои файлы. Всегда явный список: git add scripts/x.py AGENTS.md. Никогда git add -A, git add ., git commit -a — это заберёт чужую незавершённую работу.
  5. Worktree не в %TEMP%. Temp одноразовая: очистка системы удалит незакоммиченную работу безвозвратно. Постоянные worktree — только рядом с репозиторием.
  6. Перед коммитом — гейт: scripts/check_parallel_sessions.py (11-й pre-commit). Показывает все чужие деревья, их ветки и незакоммиченные файлы; BLOCK, если застейдженный файл изменён в другом дереве или это реестр, который трогает другая сессия.
  7. Правило §19.4 на отсутствие: «нет в этом дереве» ≠ «нет нигде». Прежде чем объявить пропажу — спросить все деревья (git worktree list) и только потом делать вывод.

Что можно и нельзя класть в реестры

Реестры — публичный документ в публичном репо. Что попало в дневник, то опубликовано.

В реестр ✅ В реестр ❌
наш вывод и вердикт выгрузка чужой страницы/профиля целиком
sha256 + URL первоисточника личные email третьих лиц
короткая цитата по делу (1–2 строки) блоки Location/Joined/Education
имя автора как атрибуция идеи + ссылка вендоренный файл без LICENSE/NOTICE
числа с командой и знаменателем числа без referent'а
  • Вендоренные чужие файлы (как experiments/4A_unit_of_return/frozen/crystal_catalogue_2026-09-26.md, Apache-2.0, Spanda Works LLC) держать только с provenance-заголовком + копией лицензии. Apache-2.0 §4(c): если у оригинала есть NOTICE — его обязан воспроизвести. Сейчас NOTICE не воспроизведён — это зафиксированное отступление, не скрытая утечка.
  • Замер 2026-10-03 (дневники): персональных данных в 5 реестрах — 0. Имена третьих лиц встречаются как атрибуция идей (40 вхождений «Tom Jones» в 20 файлах) — это нормальная практика цитирования, при условии что рядом есть ссылка.

Windows subprocess (§5.16)

  • NEVER use subprocess.run(capture_output=True) in daemon threads — pipe buffer deadlock on Windows.
  • ALWAYS use subprocess.Popen(stdout=PIPE, stderr=DEVNULL) + communicate(timeout=N).
  • Add creationflags=CREATE_NO_WINDOW on Windows to prevent console window creation in daemon threads.
  • Root cause: MCP server redirects sys.stdout (JSON-RPC), capture_output pipes conflict with OS descriptors → git blocks on write, Python waits for git → deadlock.
  • Applies to any background thread calling external processes (git, python, npm, etc.).

7. SELF-CHECK BEFORE COMPLETING

  1. Did I update the index after writing? (notify_change + codebase(action="index", path="status"))

  2. Are paths in correct format? (Windows for MCP, POSIX for terminal)

  3. Did I avoid retrying failed tools?

  4. Is the code production-ready (no stubs/TODOs)?

  5. Did I update AGENT_DIARY.md?

  6. Did I log the incident in project memory? (intel_log_incident)

  7. Did I check diagnostics?

  8. Did I run python -m pytest tests/ -k write_tools -v before committing?

  9. CI проверен через gh run view --log-failed (последний ран — механический guard против «CI green» на словах):

    • Перед push: последний ран не красный. После push: новый ран зелёный на ВСЕХ джобах — ubuntu + windows (Python 3.14); локальный Windows-прогон слеп к POSIX-фейлам (WISDOM 2026-08-08).
    • Точные фейлы даёт gh run view --log-failed — аннотации GitHub показывают только «exit code 1».

  10. bash scripts/verify_clean_state.sh — проверка с чистого состояния (clone + venv + install + tests)

    • Вывод должен содержать: CLEAN STATE VERIFICATION: PASSED
    • Результат вставляется в [🏁 ИТОГ] как verified_from_clean_state: <output> 10b. LIVE-SMOKE обязателен для изменений в серверах/индексе/провайдерах (инцидент 2026-08-13: 7 search-тестов были зелёными по НЕВЕРНОЙ причине — MagicMock is_reindexing truthy; reranker не запускался весь день — тесты не видят реальные сервисы).
    • python scripts/smoke_e2e.py --project <root> — реальный embed (llama.cpp 8080), реальный rerank (BGE-M3 8081), реальный векторный поиск по реальному индексу (LanceDB) — БЕЗ моков.
    • Вывод должен содержать: SMOKE E2E: PASSED.
    • «Зелёный pytest ≠ работает»: для runtime-изменений ✅ в [🏁 ИТОГ] обязан содержать live-check: <команда> → <вывод>, а не только pytest.
    • Вердикт, вычислимый кодом, — только кодом: LLM-судья запрещён там, где ответ детерминирован (попадание gold, исполнение SQL, пороги); LLM судит только смысл.

  11. All correct? → TASK VERIFIED

  12. Root чистый? (нет новых одноразовых скриптов/логов в корне — §0.6)

  13. Синхронизация лаборатории с портфолио (обязательна после ЛЮБОЙ эксперимент-серии или изменения вывода):

    • Файлы: <portfolio-root>\src\data\lab\experiments.json (+ experiments.ru.json) — эксперименты и отрицательные результаты; при необходимости diary.json/known-issues.json (и RU-зеркала). Портфолио — публичное зеркало этой лаборатории, рассинхрон = публичный неточный claim (прецеденты: KI-103 present-trap, exp-18/19 «graph не помогает» vs E5).
    • Новый эксперимент → запись с полями: id (exp-N), date, title, hypothesis, command, result, verdict, finding, chart (если есть числа), conclusion, links. Сырые числа из EXPERIMENTS_LOG.md, не по памяти.
    • Опровергнут прежний вывод → НЕ молча менять старую запись, а добавить в неё CORRECTED (…): <что опровергнуто и чем> (формат как в exp-19/E5), сохраняя историю.
    • RU-файл обновляется В ТОМ ЖЕ коммите, что и EN (конгруэнтность по id/verdict/temperature — guard-тест в tests/lab.test.ts).
    • Проверка перед коммитом портфолио: cd <portfolio-root> && pnpm test tests/lab.test.ts tests/evidence-eval.test.ts — ловит рассинхрон EN/RU и коллизии с парафраз-сетами (новые слова в корпусе могут случайно поддержать парафразу — тогда переформулировать, не трогать тест).
    • Не выполнено → статус ⚠️ портфолио не синхронизировано в [🏁 ИТОГ], даже если тесты проекта зелёные.

8. СТАБИЛЬНЫЕ ССЫЛКИ И РОТАЦИЯ ЛОГОВ (ADR-style)

  • Ссылка на факт — только (файл, SHA коммита, ID записи): EXPERIMENTS_LOG.md @ d74785d4, никогда голый :line. Живые логи ротируются/архивируются — :line сгнивает при первой архивации (прецедент: архивация KNOWN_ISSUES 429→204 сдвинула каждую строку). Цитата с SHA резолвится через git-историю навсегда; без SHA — Recalled, не Verified.
  • Каждая НОВАЯ запись несёт стабильный ID: эксперименты EXP-N, дневник YYYY-MM-DD-slug, решения ADR-стиль ADR-NNN со статусом proposed/accepted/superseded (по Nygard 2011 + adr-tools: номера последовательные, не переиспользуются; отмена — только новой supersede-записью, никогда правкой/удалением истории).
  • Ротация (обобщает §4.8 R4 для KNOWN_ISSUES.md + scripts/check_known_issues.py): живой лог >300 строк ИЛИ ежемесячно → append-only перенос закрытых/superseded записей в docs/archive/<NAME>_YYYY_MM.md; открытые остаются; коммит ротации цитируется по SHA; история публичного репо не переписывается.
  • Правки опубликованных чисел — только новой записью со ссылкой на старый ID (supersede-цепочка), никаких тихих правок.