ss-tools/axiom-mcp-agent-feedback.md

Отчёт о затруднениях при работе с Axiom MCP

Дата наблюдений: 2026-07-31
Workspace: /root/ss-tools

Назначение отчёта

Этот документ описывает исключительно затруднения, неоднозначности и неожиданное поведение, обнаруженные агентом при работе с Axiom MCP. Он не содержит оценки состояния семантической разметки проекта и не является отчётом о качестве контрактов workspace.

1. audit_contracts со scoped file_path ошибочно помечает внешние цели как отсутствующие

Наблюдаемое поведение

Вызов audit_contracts с ограничением на каталог спецификации возвращал unresolved_relation для отношений, чьи target-контракты находятся за пределами указанного file_path.

Пример класса вызова:

{
  "operation": "audit_contracts",
  "workspace_path": "/root/ss-tools",
  "file_path": "specs/036-agent-test-stabilization",
  "filter_mode": "prefix",
  "detail_level": "full"
}

Среди reported missing targets были контракты, которые затем успешно находились глобальным search_contracts, например:

• Services.AgentRuns.Service
• Schemas.AgentRun
• Spec.LlmAnalysisPlugin.ScreenshotService
• AgentChat.GradioApp
• несколько Doc.Adr.* контрактов

Почему это затрудняет работу агента

Результат выглядит как реальная ошибка графа и провоцирует агента редактировать корректные @RELATION. Чтобы отличить настоящее отсутствие target от артефакта scope, требуется вручную выполнять глобальный search_contracts для каждого warning.

Ожидаемое поведение

Scoped audit должен ограничивать набор проверяемых source-контрактов, но разрешать relation targets по полному workspace index.

Альтернативно warning должен явно различать случаи:

• target_missing_globally
• target_outside_audit_scope
• target_unavailable_due_to_parse_error

Предложение

Добавить в warning поля:

{
  "target_resolution_scope": "workspace|filtered_scope",
  "target_exists_globally": true,
  "target_file_path": "backend/src/..."
}

2. Несогласованность между workspace_health и audit_contracts

Наблюдаемое поведение

Для одного и того же scoped каталога workspace_health показывал около одного unresolved relation, тогда как audit_contracts сообщал десять или пятнадцать unresolved warnings.

Оба результата были получены почти одновременно, но использовали разные provenance snapshots и разное количество контрактов:

• workspace_health ссылался на общий memory index с тысячами контрактов;
• scoped audit_contracts строил provenance с несколькими десятками контрактов и затем считал внешние targets отсутствующими.

Почему это затрудняет работу агента

Непонятно, какой показатель является authoritative completion gate. Числа невозможно сопоставить без знания внутренних правил scope resolution каждого operation.

Ожидаемое поведение

Инструменты должны использовать одинаковую семантику unresolved relation либо возвращать явное объяснение расхождения.

Предложение

Добавить в ответ:

{
  "relation_resolution_mode": "global_targets|scoped_targets",
  "source_scope": "...",
  "target_scope": "workspace"
}

Также полезен общий operation, который возвращает exact unresolved edges по тем же правилам, что и workspace_health.

3. search_contracts по exact ID фактически работает как substring search

Наблюдаемое поведение

Запрос конкретного contract ID часто возвращал очень большой набор результатов, включающий:

• сам target;
• контракты, которые ссылаются на target;
• тесты и документы, содержащие ID в body;
• частично похожие контракты.

В ответе указывался search_method: "substring" даже при запросе полного ID.

Почему это затрудняет работу агента

Для проверки существования exact relation target агенту нужен однозначный ответ: существует ли контракт с contract_id == X. Большой substring result приходится вручную фильтровать. Некоторые ответы превышали лимит вывода и сохранялись во временный файл, хотя искомый exact target находился среди первых результатов.

Ожидаемое поведение

Поддержать exact contract lookup отдельным параметром или documented field query.

Предложение

Добавить один из вариантов:

{
  "operation": "search_contracts",
  "contract_id": "Services.AgentRuns.Service",
  "match_mode": "exact"
}

или гарантировать documented query:

contract_id:"Services.AgentRuns.Service"

и возвращать отдельно:

{
  "exact_match": {...},
  "references": [...]
}

4. Чрезмерно большие ответы search_contracts

Наблюдаемое поведение

search_contracts возвращал полный body каждого match. По распространённым ID результат достигал сотен тысяч символов и автоматически обрезался execution environment.

Сообщение инструмента предлагало делегировать чтение сохранённого output-файла другому агенту. Это существенно усложняет простую проверку существования ID.

Почему это затрудняет работу агента

• расходуется контекст;
• теряется часть результатов;
• возникает лишняя зависимость от локальных временных output files;
• exact lookup превращается в многошаговую процедуру.

Предложение

Уважать include_code_excerpt=false как строгий режим без body либо добавить fields:

{
  "fields": ["contract_id", "file_path", "start_line", "end_line", "relations"]
}

Для search_contracts разумный default — metadata-only, а body возвращать только по явному запросу.

5. Ложное распознавание legacy DEF anchor внутри обычного prose/code span

Наблюдаемое поведение

В ADR присутствовало обычное inline-code упоминание формата legacy anchor:

`[DEF:id:ADR]`

Парсер интерпретировал эту строку как реальное открытие контракта. В результате появлялся synthetic contract вида:

__unclosed__Doc.Adr.ADR0003__...

и дополнительный unclosed_anchor для ID id, несмотря на наличие корректной пары настоящих opening/closing anchors.

Почему это затрудняет работу агента

• parser warning выглядит как повреждённый closing anchor;
• read_outline при этом показывал корректную пару и не раскрывал ложный nested parse;
• relation targets к настоящему контракту переставали разрешаться;
• для диагностики пришлось сравнивать read_outline, raw file и search_contracts.

Ожидаемое поведение

Legacy DEF anchors должны распознаваться только в допустимом comment/anchor context, а не внутри Markdown inline-code, fenced code blocks или произвольного prose.

Предложение

Для Markdown:

• игнорировать anchor-like tokens внутри backticks;
• игнорировать fenced code blocks, если они не объявлены как semantic contract block;
• требовать anchor в начале строки после допустимого comment prefix;
• не распознавать placeholder IDs вроде id в documentation examples.

6. read_outline и индексный parser дают разные представления одного файла

Наблюдаемое поведение

read_outline для проблемного ADR показывал одну корректно закрытую DEF-пару. search_contracts одновременно показывал synthetic unclosed contract и два parse warnings.

Почему это затрудняет работу агента

Curator workflow предписывает использовать read_outline как основной verifier до и после edit. Однако успешный read_outline не гарантировал, что full parser/index примет файл без warnings.

Ожидаемое поведение

read_outline должен использовать тот же parser и те же lexical exclusion rules, что rebuild/indexing, либо явно сообщать, что это lightweight parser и его результат недостаточен для parse validation.

Предложение

Добавить в read_outline:

{
  "parser_mode": "full|lightweight",
  "parse_warnings": [...],
  "index_equivalent": true
}

Или предоставить отдельный быстрый validate_file operation с тем же parser, который используется при rebuild.

7. Full rebuild выполнялся значительно дольше заявленного/default timeout

Наблюдаемое поведение

Был запущен async full rebuild:

{
  "operation": "rebuild",
  "rebuild_mode": "full",
  "async_op": true,
  "timeout_seconds": 120
}

Job продолжал находиться в состоянии running после примерно 400 секунд. timeout_seconds не остановил job и не сформировал timeout result.

Почему это затрудняет работу агента

• непонятно, относится timeout к запуску, polling request или самому rebuild job;
• обязательный verification loop блокируется;
• многократный polling расходует execution-step budget;
• нет ETA или phase progress, поэтому невозможно отличить нормальную долгую операцию от зависания.

Ожидаемое поведение

Документация и ответ должны чётко определять semantics timeout. Для async job нужен progress и состояние heartbeat.

Предложение

Возвращать:

{
  "status": "running",
  "phase": "scan|parse|edges|duckdb_persist|swap",
  "files_processed": 1200,
  "files_total": 2423,
  "contracts_parsed": 5000,
  "last_progress_at": "...",
  "estimated_remaining_seconds": 80,
  "cancel_supported": true
}

Также полезны:

• cancel_rebuild;
• server-side max runtime;
• предупреждение о превышении requested timeout;
• blocking rebuild, который реально соблюдает timeout.

8. Частый polling не предлагает backoff или wait-until-change

Наблюдаемое поведение

rebuild_status немедленно возвращал running, поэтому агент был вынужден многократно вызывать operation. В API нет параметра ожидания изменения состояния или рекомендуемого следующего poll interval.

Почему это затрудняет работу агента

При долгом rebuild это быстро расходует лимит tool calls/agent steps.

Предложение

Добавить long-poll semantics:

{
  "operation": "rebuild_status",
  "job_id": "...",
  "wait_for_change_seconds": 30
}

И возвращать:

{
  "recommended_poll_after_seconds": 15
}

9. status не отражал активный async rebuild

Наблюдаемое поведение

Во время работающего rebuild job вызов status возвращал:

• active_generation: null;
• старое время последнего full rebuild;
• index_status: FRESH.

При этом rebuild_status для job всё ещё возвращал running.

Почему это затрудняет работу агента

Нельзя по status понять:

• выполняется ли rebuild;
• будет ли текущий fresh index скоро заменён;
• относится ли status к serving snapshot или in-progress generation;
• не потерян ли job.

Ожидаемое поведение

status должен показывать serving index отдельно от active generation.

Предложение

{
  "serving_index": {
    "status": "FRESH",
    "snapshot_generated_at": "..."
  },
  "active_generation": {
    "job_id": "...",
    "status": "running",
    "started_at": "...",
    "phase": "parse"
  }
}

10. Provenance timestamps и contract counts различались между почти одновременными operations

Наблюдаемое поведение

Параллельные вызовы workspace_health и audit_contracts возвращали разные:

• snapshot_generated_at;
• contract_count;
• edge_count;
• source (memory/scoped memory snapshot).

Часть различий объясняется scope, но это не было явно обозначено в структуре provenance.

Почему это затрудняет работу агента

Возникает сомнение, сравниваются ли результаты одного index generation. Нельзя надёжно вычислить «до/после», если operations могут использовать разные snapshots.

Предложение

Добавить единый immutable index_generation_id во все search/audit responses. Для scoped operations отдельно указывать:

{
  "index_generation_id": "...",
  "global_contract_count": 7978,
  "scoped_contract_count": 33,
  "global_edge_count": 3829,
  "scoped_edge_count": 34
}

Также полезно разрешить клиенту закрепить серию запросов за generation ID.

11. Неясная семантика index_age_seconds: 0 в audit responses

Наблюдаемое поведение

audit_contracts возвращал index_age_seconds: 0 и свежий snapshot_generated_at, хотя persistent full index был создан раньше. Вероятно, operation формировал transient scoped snapshot, но это не пояснялось.

Почему это затрудняет работу агента

Показатель можно ошибочно интерпретировать как подтверждение недавнего full rebuild.

Предложение

Разделить:

• serving_index_age_seconds;
• audit_view_generated_at;
• audit_view_scope;
• audit_view_source_generation_id.

12. audit_belief_protocol игнорировал переданный file scope в поле scope

Наблюдаемое поведение

Вызов передавал file_path и filter_mode, но ответ содержал:

"scope": "workspace"

и не показывал, был ли scope реально применён.

Почему это затрудняет работу агента

Невозможно понять, означает total: 0 отсутствие findings в нужной директории или по всему workspace. Это особенно важно при обязательном scoped verification.

Предложение

Возвращать нормализованный applied scope:

{
  "scope": {
    "mode": "file_path",
    "file_path": "specs/036-agent-test-stabilization",
    "filter_mode": "prefix",
    "matched_contracts": 30
  }
}

Если operation не поддерживает scope, он должен отклонить неизвестные/неприменимые параметры, а не молча вернуть workspace result.

13. Недостаточно явное различие между parse warnings и unresolved graph edges

Наблюдаемое поведение

Один parser false positive делал реальный contract недоступным для relation resolution. В downstream audit это выглядело только как unresolved_relation, без ссылки на первичную parse problem target-файла.

Почему это затрудняет работу агента

Агент может исправлять relation source, хотя первопричина находится в target file parser failure.

Предложение

При unresolved target проверять parser diagnostics по вероятному target и возвращать causal chain:

{
  "code": "unresolved_relation",
  "target_id": "Doc.Adr.ADR0003",
  "resolution_failure": "target_parse_failed",
  "target_parse_warnings": [
    {
      "file_path": "docs/adr/...",
      "code": "unclosed_anchor"
    }
  ]
}

14. Нужен специализированный operation для exact relation validation

Проблема

Текущий workflow для проверки одного warning требует:

1. получить warning из audit;
2. извлечь target ID из текстового message;
3. вызвать substring search_contracts;
4. вручную найти exact match;
5. определить, является ли warning scope artifact или parser failure.

Предложение

Добавить operation вроде:

{
  "operation": "resolve_relation_target",
  "source_contract_id": "...",
  "target_contract_id": "..."
}

Ответ:

{
  "resolved": true,
  "exact_target": {...},
  "outside_source_scope": true,
  "parse_blocked": false,
  "candidate_renames": []
}

15. Нужна возможность получить только итоговые parse warnings конкретного rebuild job

Наблюдаемое затруднение

После async rebuild агент должен подтвердить требование «0 parse warnings». Однако rebuild_status во время выполнения показывал только status и elapsed time. Не было ясно, где после завершения получить warnings именно этого job, не смешивая их с предыдущим serving snapshot.

Предложение

Финальный job result должен включать:

{
  "job_id": "...",
  "status": "completed",
  "index_generation_id": "...",
  "parse_warning_count": 0,
  "parse_warnings": [],
  "contract_count": 0,
  "edge_count": 0,
  "duration_seconds": 0
}

И status должен ссылаться на тот же index_generation_id после atomic swap.

16. Ошибки/неоднозначности документации tool surface

Наблюдаемое затруднение

Инструкции окружения описывали Axiom через логические task-shaped capabilities и resource URI, тогда как фактически доступный tool surface состоял из axiom_search и axiom_audit с operation enum. Дополнительно skill-документация местами упоминала reindex, но enum фактического tool schema предоставлял rebuild и не предоставлял отдельный reindex operation.

Почему это затрудняет работу агента

Приходится сопоставлять три уровня терминологии:

• MCP server conceptual capabilities;
• skill-документацию;
• фактическую JSON schema подключённых tools.

При конфликте агент вынужден угадывать, какой operation реально существует.

Предложение

• генерировать skill tool reference из фактической MCP schema;
• публиковать version/capabilities endpoint;
• возвращать friendly unsupported-operation error с ближайшими допустимыми operations;
• убрать или маркировать aliases, которые не представлены в schema.

Приоритет исправлений

Критический

1. Scoped audit должен разрешать targets глобально или явно маркировать scope artifacts.
2. Legacy anchor parser не должен распознавать примеры внутри Markdown inline code/fences.
3. read_outline и rebuild parser должны давать согласованные parse diagnostics.
4. Async rebuild должен показывать progress, active generation и предсказуемую timeout semantics.

Высокий

5. Exact contract-ID lookup без body и substring noise.
6. Единый index_generation_id во всех responses.
7. Причинная связь unresolved_relation → target parse failure.
8. Applied scope должен явно возвращаться всеми audit operations.

Средний

9. Long polling/backoff для rebuild status.
10. Поля выбора response payload для экономии контекста.
11. Финальный parse-warning report, привязанный к rebuild job.
12. Синхронизация документации с фактической tool schema.

Минимальный рекомендуемый regression-набор для MCP

1. Создать два контракта в разных директориях; scoped audit source-директории должен успешно разрешать target во второй директории.
2. Поместить `[DEF:id:ADR]` в Markdown prose; parser не должен создавать contract.
3. Поместить DEF anchor example в fenced code block; parser не должен создавать contract.
4. Для одного файла сравнить read_outline.parse_warnings и full rebuild parse warnings — результаты должны совпасть.
5. Запустить async rebuild и проверить, что status.active_generation.job_id совпадает с job.
6. Проверить timeout/cancel semantics долгого rebuild.
7. Выполнить exact lookup существующего ID — должен вернуться один exact target без full body.
8. Выполнить exact lookup отсутствующего ID — должен вернуться однозначный exact_match: null.
9. Сравнить workspace_health и audit_contracts на одном generation ID — unresolved edge counts должны быть объяснимо согласованы.
10. Передать scope в audit_belief_protocol — response должен показать фактически применённый scope либо вернуть unsupported-scope error.

Материал для включения в план доработки Axiom

17. Архитектурный вердикт и рекомендуемая роль Axiom

Решение

Axiom имеет смысл сохранять и развивать, поскольку queryable semantic graph даёт возможности, которых недостаточно у обычной inline-документации:

• поиск входящих и исходящих архитектурных связей;
• workspace-wide impact analysis;
• поиск связанных ADR и тестов;
• выявление dangling relations;
• cross-stack traceability;
• анализ semantic neighborhoods и dependency paths.

Однако текущая реализация пока не должна использоваться как самостоятельный источник истины или как основание для автоматических destructive edits.

Рекомендуемая модель доверия:

Source code + inline contracts + ADR + tests = authoritative source
Axiom index = derived searchable projection
Axiom audit findings = hypotheses requiring verification

Рекомендуемый operational status до выполнения критических acceptance criteria:

KEEP — ADVISORY MODE

Не рекомендуется:

AUTHORITATIVE / MANDATORY MUTATION GATE

Причина

На практике MCP уже помогает искать связи в большом multi-stack workspace, но выявленные scope inconsistencies, parser false positives и непрозрачный rebuild lifecycle создают риск ошибочных правок. Это не аргумент в пользу удаления semantic index; это аргумент в пользу отделения inline SSOT от производного индекса и укрепления границ доверия.

18. Сравнение с простым поддержанием inline-документации

Оценка по шкале 1–10:

Критерий	Axiom сейчас	Inline-only	Axiom после исправлений
Локальная точность	5	9	8
Межмодульная навигация	7	5	9
Exact lookup	4	8	9
Impact analysis	8	4	9
Graph integrity audit	6	3	9
Детерминированность	4	8	8
Безопасность автоматических решений	4	8	8
Эксплуатационная простота	3	9	7
Работа с большим workspace	7	4	9
Архитектурная память	8	6	9

Ориентировочный итог:

• текущий Axiom: 5.3/10;
• inline-only: 7.0/10;
• исправленный Axiom как derived index: 8.3/10.

Вывод для планирования

• Для локальных изменений в 1–3 файлах inline workflow остаётся основным и более эффективным.
• Для изменений в 3–10 связанных модулях Axiom должен быть optional accelerator.
• Для workspace-wide refactoring, contract rename/move и архитектурного impact analysis Axiom должен быть рекомендуемым инструментом.
• Full rebuild не должен быть обязательным после изменения только текста @BRIEF, @RATIONALE или другого metadata, не влияющего на graph identity/boundaries.

19. Целевое состояние продукта

Product objective

Сделать Axiom надёжным derived semantic index, который:

1. никогда не заставляет агента исправлять корректный source из-за audit scope artifact;
2. не создаёт contracts из документационных примеров;
3. предоставляет exact lookup как базовую операцию;
4. использует единый generation identity во всех operations;
5. объясняет причинную связь между parser failure и downstream graph warning;
6. имеет наблюдаемый и управляемый rebuild lifecycle;
7. уменьшает количество ручного grep/AST анализа на больших задачах;
8. не добавляет значительный overhead к локальным изменениям.

Non-goals

В план не следует включать следующие цели:

• сделать Axiom владельцем source contracts;
• автоматически редактировать исходники по одному audit warning;
• добиваться нулевого orphan count путём генерации фиктивных relations;
• заменять тесты, линтеры, AST и raw source verification;
• требовать full workspace rebuild после любой документационной правки;
• использовать fuzzy search как доказательство существования exact target.

20. Предлагаемые workstreams

WS1 — Consistent relation resolution

Цель: scoped operations фильтруют source contracts, но relation targets разрешаются по полному generation snapshot.

Задачи:

1. Определить canonical resolution semantics для всех operations.
2. Разделить source_scope и target_resolution_scope.
3. Исправить scoped audit_contracts.
4. Согласовать unresolved counts с workspace_health.
5. Добавить structured resolution reason.
6. Добавить exact target path и global-existence marker в warnings.

Acceptance criteria:

• cross-directory target не считается missing при scoped source audit;
• workspace_health и audit_contracts на одном generation ID возвращают согласованный набор unresolved edges;
• scope artifacts не попадают в unresolved_relation без отдельной маркировки;
• source audit не требует ручного global search для каждого корректного external target.

WS2 — Unified parser and Markdown lexical safety

Цель: один parser и единые lexical rules используются в outline, validation и rebuild.

Задачи:

1. Вынести canonical parser pipeline.
2. Использовать его в read_outline, rebuild и audits.
3. Игнорировать anchor-like text внутри Markdown inline code.
4. Игнорировать fenced examples, если block не объявлен semantic contract.
5. Требовать допустимый line prefix/anchor position.
6. Добавить diagnostics для ambiguous anchors.
7. Добавить file-level parser validation operation.

Acceptance criteria:

• `[DEF:id:ADR]` в prose не создаёт contract;
• DEF/region examples в fenced code block не создают contracts;
• read_outline и full rebuild возвращают одинаковый набор parse warnings для одного file revision;
• закрытая реальная anchor pair не превращается в synthetic unclosed contract из-за prose;
• parser errors содержат line, column, lexical context и recovery reason.

WS3 — Exact discovery and bounded responses

Цель: агент может за один вызов проверить существование exact contract ID без больших body payloads.

Задачи:

1. Добавить match_mode=exact или отдельный exact operation.
2. Разделить exact match и textual references.
3. Сделать metadata-only response default.
4. Добавить fields/include_body selection.
5. Добавить exact lookup для отсутствующего ID.
6. Добавить rename candidates отдельным opt-in режимом.

Acceptance criteria:

• exact lookup существующего ID возвращает ровно один exact node;
• exact lookup отсутствующего ID возвращает exact_match: null;
• response не содержит полный body без явного запроса;
• textual references не смешиваются с exact node;
• типичный exact lookup укладывается в небольшой bounded payload.

WS4 — Generation identity and snapshot consistency

Цель: все результаты можно доказуемо связать с одним immutable index generation.

Задачи:

1. Ввести index_generation_id.
2. Добавить его во все search/audit/status/job responses.
3. Разделить global и scoped counts.
4. Разделить serving snapshot и transient audit view.
5. Разрешить pin operations к generation ID.
6. Возвращать stale-generation error при невозможности выполнить pinned query.

Acceptance criteria:

• параллельные operations на одном generation ID используют одинаковую graph base;
• scoped response явно показывает global/scoped counts;
• index_age_seconds не смешивает возраст serving snapshot и время создания audit view;
• агент может провести серию health/audit/search запросов на одном snapshot.

WS5 — Observable async rebuild lifecycle

Цель: rebuild имеет понятный progress, timeout, cancellation и atomic activation.

Задачи:

1. Определить semantics timeout_seconds.
2. Добавить phases и progress counters.
3. Добавить heartbeat и last_progress_at.
4. Добавить recommended poll interval или long polling.
5. Добавить cancellation.
6. Показывать active generation в status.
7. Возвращать final job report с parse warnings.
8. Связывать completed job с serving generation после atomic swap.
9. Определить поведение stuck/failed/coalesced jobs.

Acceptance criteria:

• status.active_generation.job_id совпадает с running job;
• progress изменяется или job явно признаётся stalled;
• timeout semantics документирована и покрыта тестом;
• клиент может отменить rebuild либо получает явный cancel_supported=false;
• final result содержит duration, counts, warnings и generation ID;
• после swap serving index ссылается на generation completed job;
• polling не требует десятков быстрых tool calls.

WS6 — Causal diagnostics

Цель: downstream graph warnings указывают первичную причину.

Задачи:

1. Ввести resolution_failure enum.
2. Связывать unresolved target с target parse diagnostics.
3. Различать globally missing, parse failed, outside scope, tombstoned, renamed candidate.
4. Возвращать structured warning fields вместо необходимости парсить message.
5. Добавить suggested next operation.

Acceptance criteria:

• при target parse failure source warning содержит target file и parser warning;
• globally missing target явно отличается от outside-scope target;
• агенту не требуется извлекать ID из human-readable message;
• warning указывает безопасный следующий diagnostic step, но не предлагает destructive mutation без подтверждения.

WS7 — Applied scope contract

Цель: каждый operation либо применяет переданный scope и возвращает его, либо отклоняет unsupported scope.

Задачи:

1. Унифицировать scope schema.
2. Добавить applied scope во все ответы.
3. Запретить silent ignore parameters.
4. Добавить matched source count.
5. Документировать scope behavior каждого operation.

Acceptance criteria:

• audit_belief_protocol явно показывает фактически применённый scope;
• unsupported scope приводит к typed error;
• одинаковый scope object используется в workspace_health, audits и search;
• response показывает matched contracts/files.

WS8 — Documentation and schema synchronization

Цель: агент видит один непротиворечивый tool reference.

Задачи:

1. Генерировать operation catalog из runtime schema.
2. Добавить capabilities/version endpoint.
3. Версионировать response contracts.
4. Удалить или пометить отсутствующие aliases.
5. Добавить examples для exact lookup, scoped audit и rebuild.
6. Добавить migration notes при изменении operations.

Acceptance criteria:

• skill/reference не перечисляет operations, отсутствующие в schema;
• unsupported operation возвращает typed error и ближайшие допустимые значения;
• server version и schema version доступны агенту;
• examples проходят automated contract tests.

WS9 — Incremental verification policy

Цель: стоимость проверки соответствует типу изменения.

Задачи:

1. Классифицировать mutations:
   • metadata text only;
   • relation change;
   • contract ID change;
   • anchor boundary change;
   • file move/delete.
2. Реализовать file-level validate.
3. Реализовать incremental rebuild с удалением stale nodes/edges.
4. Оставить full rebuild для structural/global cases.
5. Возвращать recommended verification mode.

Acceptance criteria:

• metadata-only edit не требует full workspace rebuild;
• relation/ID/boundary changes гарантированно обновляют affected graph;
• deletion удаляет stale edges;
• incremental result проверяем против периодического full rebuild;
• tool возвращает reason, почему выбран incremental или full mode.

WS10 — Agent safety policy

Цель: MCP findings не приводят к неправильным автоматическим source mutations.

Задачи:

1. Маркировать confidence и evidence class.
2. Ввести advisory/verified finding state.
3. Запретить mutation recommendation для scope artifacts.
4. Требовать exact target verification перед relation removal.
5. Документировать safe workflow для curator agents.

Acceptance criteria:

• одиночный fuzzy/scoped warning не классифицируется как verified missing target;
• relation removal recommendation появляется только после global exact lookup и parser validation;
• findings содержат evidence used;
• agent-facing documentation подчёркивает derived-index trust model.

21. Приоритеты и предлагаемая последовательность

Phase 0 — Зафиксировать модель доверия

Приоритет: немедленно.

Deliverables:

• documented advisory status;
• source/inline/tests declared authoritative;
• запрет automatic relation mutation по scoped warning;
• временная инструкция для агентов по independent confirmation.

Exit criteria:

• все agent prompts и skill references используют одинаковую trust model;
• отсутствуют инструкции, требующие destructive edit только по одному aggregate finding.

Phase 1 — Устранить опасные false positives

Приоритет: критический.

Включает:

• WS1 relation resolution;
• WS2 parser safety;
• WS6 causal diagnostics;
• WS7 applied scope.

Exit criteria:

• scoped external relations разрешаются корректно;
• Markdown examples не создают contracts;
• outline/rebuild parser diagnostics согласованы;
• primary parse failure виден в downstream warning.

Phase 2 — Сделать MCP пригодным для детерминированной агентской работы

Приоритет: высокий.

Включает:

• WS3 exact discovery;
• WS4 generation identity;
• WS5 rebuild observability.

Exit criteria:

• exact lookup выполняется одним bounded вызовом;
• серии запросов pin-ятся к generation;
• rebuild полностью наблюдаем и имеет финальный отчёт.

Phase 3 — Снизить эксплуатационный overhead

Приоритет: высокий/средний.

Включает:

• WS9 incremental verification;
• response field selection;
• long polling/backoff;
• rebuild coalescing semantics.

Exit criteria:

• локальная metadata-правка не запускает многоминутный full rebuild;
• типичный curator workflow использует существенно меньше tool calls;
• full rebuild остаётся доступным как periodic integrity gate.

Phase 4 — Обновить документацию и провести benchmark

Приоритет: средний.

Включает:

• WS8 schema synchronization;
• WS10 safety policy;
• benchmark Axiom vs inline-only.

Exit criteria:

• documentation generated/tested against actual schema;
• benchmark report показывает реальную пользу или обосновывает упрощение продукта;
• принято решение advisory vs mandatory для отдельных operation classes.

22. Backlog в формате задач

P0

• Исправить global target resolution в scoped audit_contracts.
• Добавить lexical exclusions для Markdown inline-code и fenced examples.
• Унифицировать parser read_outline и rebuild.
• Вернуть applied scope или typed unsupported-scope error.
• Добавить resolution_failure и causal target parse diagnostics.
• Зафиксировать advisory trust policy в agent-facing документации.

P1

• Реализовать exact contract lookup.
• Сделать body opt-in для search_contracts.
• Добавить immutable index_generation_id.
• Добавить generation pinning для search/audit operations.
• Показывать active rebuild в status.
• Добавить rebuild phases/progress/heartbeat.
• Добавить final rebuild report с parse warnings.
• Добавить long polling или recommended poll interval.

P2

• Добавить cancellation/stalled detection для rebuild.
• Реализовать file-level validation.
• Определить безопасную incremental rebuild policy.
• Добавить field selection для bounded responses.
• Синхронизировать skill reference с runtime schema.
• Добавить capabilities/version endpoint.
• Добавить structured exact relation resolver.

P3

• Реализовать benchmark harness Axiom vs grep/AST workflow.
• Измерять false-positive и false-negative rates.
• Измерять tool-call/context overhead.
• Добавить telemetry по rebuild phases и query latency.
• Рассмотреть упрощение health scoring, если benchmark не подтверждает пользу.

23. Definition of Done для critical release

Critical release Axiom считается готовым к расширенному использованию, когда выполнены все условия:

1. Ни один scoped audit test не помечает существующий global target как missing.
2. Parser corpus не создаёт contracts из Markdown examples.
3. read_outline и rebuild возвращают одинаковые diagnostics на одном file hash.
4. Каждый response содержит index_generation_id или явно объясняет отсутствие generation binding.
5. Exact lookup существующего и отсутствующего ID детерминирован.
6. Rebuild job виден в status, показывает progress и выдаёт final warning report.
7. Все operations возвращают applied scope.
8. Unresolved warnings содержат typed resolution cause.
9. Agent documentation объявляет source authoritative, index derived.
10. Regression suite покрывает все воспроизведённые в этом документе проблемы.

24. Go / No-Go gates после доработки

Go: сохранить Axiom как активно развиваемый semantic layer

Нужно достичь:

• false-positive rate unresolved findings < 1–2%;
• отсутствие parser-created contracts из prose/examples;
• exact lookup accuracy 100% на regression corpus;
• не менее 30% сокращения времени workspace-wide impact analysis;
• не менее 50% сокращения пропущенных cross-module consumers относительно inline-only workflow;
• не более 10% overhead на обычных задачах, где Axiom действительно нужен;
• локальные задачи не блокируются full rebuild;
• 100% воспроизводимость audit results на pinned generation.

Conditional Go: оставить только advisory search/index

Если graph search полезен, но audit confidence остаётся недостаточным:

• сохранить exact lookup;
• сохранить incoming/outgoing relations;
• сохранить impact analysis;
• отключить mandatory health gates;
• не использовать автоматические remediation suggestions;
• выполнять full integrity audit только периодически.

No-Go: сократить Axiom до минимального индекса или удалить MCP layer

Рассматривать, если после исправлений:

• false positives остаются >5%;
• parser и outline продолжают расходиться;
• rebuild остаётся непрозрачным или нестабильным;
• крупные задачи не ускоряются хотя бы на 20–30%;
• agent workflow требует больше ручной перепроверки, чем inline/grep/AST;
• индекс регулярно провоцирует неправильные source edits.

25. Метрики для benchmark и эксплуатации

Correctness

• exact lookup precision/recall;
• unresolved relation false-positive rate;
• unresolved relation false-negative rate;
• parser false-positive contracts;
• parser false-negative contracts;
• outline/rebuild diagnostic agreement;
• audit reproducibility by generation ID.

Efficiency

• median/p95 query latency;
• rebuild duration;
• time to first progress update;
• tool calls per curator task;
• response bytes/tokens per lookup;
• time to build working context;
• full vs incremental rebuild ratio.

Agent safety

• incorrect edits caused by MCP findings;
• findings requiring manual global recheck;
• scope artifacts reported as errors;
• mutations attempted without exact verification;
• number of rollback events after MCP-driven change.

Product value

• time saved on impact analysis;
• consumers discovered only through semantic graph;
• ADR/test links found automatically;
• regressions prevented by dangling-edge detection;
• percentage of tasks where Axiom was useful vs pure overhead.

26. Рекомендуемая временная инструкция агентам до исправления MCP

1. Treat Axiom as advisory, not authoritative.
2. Source code, inline contracts, ADRs, AST and tests remain authoritative.
3. Never remove or rename a relation solely from scoped audit output.
4. Verify every missing target with exact global source search.
5. Check target parser diagnostics before editing the source relation.
6. Use read_outline for navigation, but do not treat it as proof of full-parser validity.
7. Avoid full rebuild for metadata-only edits unless current policy technically forces it.
8. Record the rebuild job ID and verify final generation before declaring completion.
9. Do not add meaningless relations solely to reduce orphan metrics.
10. Escalate when Axiom operations disagree on the same generation or scope.

27. Рекомендованный итог для product plan

Краткая формулировка, которую можно перенести в roadmap:

Сохранить Axiom как derived semantic graph для больших multi-agent workspaces, но временно использовать его в advisory mode. В первую очередь устранить scoped relation false positives, parser divergence и непрозрачность rebuild. Затем добавить exact lookup, immutable generation IDs и incremental verification. После critical fixes провести сравнительный benchmark с inline/grep/AST workflow. Mandatory gating разрешать только для операций, чья точность и воспроизводимость подтверждены измерениями.