gennady 0.8.3 → 0.8.4-next.1

package/README.md

@@ -21,6 +21,24 @@ npx gennady
 npx gennady commit
 ```
 
+### 🔧 Установка из исходников
+
+Если `npx gennady` недоступен (например, корпоративный npm-registry возвращает `403`):
+
+```bash
+git clone https://github.com/rubaxa/gennady
+cd gennady
+npm ci
+npm run build
+npm link
+
+gennady help
+```
+
+- Для стабильной работы собирайте релизный тег (`git checkout v0.8.4`), а не `main`.
+- После правок кода пересоберите: `npm run build` (повторный `npm link` не нужен).
+- Для разработки без сборки: `npm run dev -- <команда>`.
+
 ---
 
 ## 🧩 Что нужно в окружении
@@ -73,6 +91,7 @@ npx gennady commit --apply
 npx gennady cat ./src
 npx gennady cat "./src/**/*.ts" --output=md
 npx gennady cat ./src --plain
+npx gennady cat --url="https://gitlab.com/.../-/merge_requests/123"
 ```
 
 **Опции:**
@@ -81,6 +100,22 @@ npx gennady cat ./src --plain
 - `--plain`: без ANSI-цветов
 - `--exclude`, `-e`: исключить паттерны
 - `--ext`: фильтр по расширениям
+- `--url`: MR/PR URL для удалённого сбора файлов
+
+---
+
+### 🔍 `review`
+
+AI-ревью staged изменений.
+
+```bash
+npx gennady review
+npx gennady review --branch=develop
+```
+
+**Опции:**
+
+- `--branch`, `-b`: target branch для diff (по умолчанию origin/main)
 
 ---
 
@@ -160,7 +195,6 @@ echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
   npx gennady vcs-reply --project=group/project --iid=123
 
 # Проверка без отправки
-
 echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
   npx gennady vcs-reply --project=group/project --iid=123 --dry-run
 ```
@@ -179,19 +213,212 @@ echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
 
 ---
 
+### 🧹 `lint`
+
+Валидация TypeScript-файлов: file-header, anchors, DbC-контракты, invariant-count.
+
+```bash
+npx gennady lint ./src
+npx gennady lint --staged
+npx gennady lint ./src --autofix --verbose
+```
+
+**Опции:**
+
+- `--autofix`: автоисправление DbC-контрактов
+- `--staged`: только staged и untracked `.ts` (взаимоисключающий с путями)
+- `--verbose`, `-v`: debug-логи
+- `--max-invariants`: макс. инвариантов на сущность (по умолчанию 3)
+- `--exclude`: исключить файлы по glob (повторяемый)
+
+---
+
+### 🗯️ `alt-opinion`
+
+Мульти-модельные мнения с опциональным синтезом.
+
+```bash
+# Мнение двух моделей с синтезом
+npx gennady alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="./spec.md"
+
+# Через stdin
+cat spec.md | npx gennady alt-opinion \
+  --model="llmproxy/gpt-4o" \
+  --model="openrouter/claude-sonnet"
+```
+
+**Опции:**
+
+- `--model`: дескриптор модели `provider/model[::prompt.md]` (повторяемый)
+- `--synthModel`: модель-синтезатор
+- `--file`: путь к входному файлу
+- `--modelPrompt`: промпт для всех моделей
+- `--synthPrompt`: промпт для синтезатора
+- `--strict`: exit 1 при ошибке любой модели
+
+---
+
+### 🔄 `sync`
+
+Синхронизация `ai/directives/` из npm-пакета в текущий проект.
+
+```bash
+npx gennady sync
+npx gennady sync --dry-run
+npx gennady sync ts-patterns typescript --dry-run
+```
+
+**Опции:**
+
+- `--dry-run`: предпросмотр без записи
+
+---
+
+### 🔄 `sync-skills`
+
+Синхронизация SDD-навыков из `ai/skills/` в `.claude/skills/` проекта.
+
+```bash
+npx gennady sync-skills
+npx gennady sync-skills --dry-run
+npx gennady sync-skills sdd-execute
+```
+
+**Опции:**
+
+- `--dry-run`: предпросмотр без записи
+
+---
+
+### 🧭 `orient`
+
+Навигация по проекту: file-header разметка, DBC-контракты, граф зависимостей.
+
+```bash
+npx gennady orient                          # карта проекта
+npx gennady orient --task=TSK-03            # файлы задачи
+npx gennady orient --consumer=DbcTsLinter   # кто потребляет модуль
+npx gennady orient --file=path/to/file.ts   # детальный просмотр
+npx gennady orient --graph                  # граф зависимостей
+npx gennady orient --specs                  # обзор спек
+```
+
+**Опции:**
+
+- `--file`, `--task`, `--consumer`, `--entity`: поиск по атрибутам
+- `--graph`, `--specs`: обзорные режимы
+- `--fuzzy`, `--detail`, `--depth`, `--max-results`: настройки вывода
+
+---
+
+### 📋 `agents-rules`
+
+Выводит инструкцию по `orient` для AI-агентов.
+
+```bash
+npx gennady agents-rules
+```
+
+---
+
+### 🖥️ `remote-console`
+
+Зеркалирование браузерной консоли в локальный stdout.
+
+```bash
+npx gennady remote-console
+npx gennady remote-console --port=8080
+npx gennady remote-console --url="https://example.com"
+```
+
+**Опции:**
+
+- `--port`, `-p`: порт (по умолчанию 43001)
+- `--host`: хост (по умолчанию localhost)
+- `--url`: URL страницы для открытия с активацией
+
+---
+
+Подробнее: [`cli/cmd/README.md`](cli/cmd/README.md).
+
+---
+
 ## 🛠️ Типовые сценарии
 
-### 1. Верификация MR
+### 1. Сделать коммит
+
+```bash
+npx gennady commit
+npx gennady commit --mode=oneline --apply --task=TSK-42
+```
+
+### 2. Проверить качество кода
+
+```bash
+npx gennady lint ./src
+npx gennady lint --staged --autofix
+```
+
+### 3. Навигация по проекту
+
+```bash
+npx gennady orient                    # карта
+npx gennady orient --task=TSK-03      # файлы задачи
+npx gennady orient --graph            # граф зависимостей
+npx gennady agents-rules              # инструкция для AGENTS.md
+```
+
+### 4. Верификация MR
 
 ```bash
 export GITLAB_PERSONAL_TOKEN="<token>"
 npx gennady review-verify --ref=group/project!123
 ```
 
-### 2. Разрешение merge-конфликтов
+### 5. AI-ревью изменений
+
+```bash
+npx gennady review
+npx gennady review --branch=develop
+```
+
+### 6. Разрешение merge-конфликтов
 
 ```bash
 git merge feature/some-branch
 # если есть конфликты
 npx gennady resolve-conflicts
 ```
+
+### 7. Собрать файлы для AI
+
+```bash
+npx gennady cat "./src/**/*.ts" --output=md --plain | pbcopy
+```
+
+### 8. Синхронизация директив и навыков
+
+```bash
+npx gennady sync
+npx gennady sync-skills
+```
+
+### 9. Мульти-модельный анализ
+
+```bash
+npx gennady alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="./spec.md"
+```
+
+### 10. Зеркалирование консоли браузера
+
+```bash
+npx gennady remote-console
+```

package/ai/directives/agent-inbox/arch-interrogation.directive.xml

@@ -0,0 +1,298 @@
+<ArchInterrogation keywords="architecture interrogation, entity interrogation, design review, yagni, premature abstraction, boundary check, decomposition, reuse, analog, package extraction, shared library, data ownership, coupling, dependency direction, one-way door, reversibility, helicopter view, c4, visualize, mr review context" type="directive" ver="1.0">
+  <Mission>
+    Interrogate every entity, data store, and flow introduced or changed by an MR, and emit a helicopter-view picture in which each element carries a justification verdict. Replace the human architect's reflex questions — "why does this exist, is there an analog, how is it done here, is this YAGNI, why two services and not one" — with a fixed, repo-grounded battery applied to all changed code.
+
+    Cognitive role: Adversarial Architecture Interrogator. The author's framing is NOT trusted on its word. The default stance is "this entity is unnecessary until its existence is proven against the actual codebase." Output is read in a chat UI, so relational findings are shown as diagrams, not prose, to keep cognitive load low — the operator drills down with follow-up questions afterwards.
+
+    Consumer: the `agent-inbox` skill, `review_needed` stage. The skill loads this directive and applies it to the MR diff + any design doc / linked spec before forming line-comments.
+  </Mission>
+
+  <SourceOfTruth>
+    Per-entity answers about analogs (axis B) and project conventions (axis D) MUST come from reading the actual repository at current HEAD — never from model prior. Stated rationale is harvested, in priority order, from: MR description, design doc inside the diff, linked spec/ticket, neighbouring ADRs/docs, commit messages. Absence of stated rationale is itself a finding.
+  </SourceOfTruth>
+
+  <InputContract>
+    Supplied by the consumer (the `agent-inbox` skill):
+    - **Required:** `ref` (`group/project!iid`) and `webUrl` (the MR page URL) — the report is bookended with this link (see `<OutputFormat>`). `diff_refs` + worktree `path` + `base` for grounded reading. `base` + `path` make the change stats computable (`git -C <path> diff --numstat <base>..HEAD` for per-file +/− lines; `--name-status` for added/deleted/renamed) — the source for the scope summary required by `AX_CHANGESET_SCALE`.
+    - **Optional:** `title`, `spec_links` (linked spec/ticket/design-doc URLs).
+    - **Optional:** `prior_threads` — existing discussion already on the MR (the `<Review_Threads>` artifact from `review-issues --all`: per-thread `file`/`line`/`resolved` and messages tagged `Reviewer` / `Author` / `AI_Agent`, each with `uid`), plus `my_login` (my GitLab username) and `my_drafts` (my unpublished notes from `review-issues --draft`). When supplied, they feed `AX_PRIOR_DISCUSSION_AWARENESS`: the interrogation reads them as context and de-duplicates against them. When absent, proceed without prior-discussion awareness and say so in the report.
+    No `webUrl` → render the bookend from `ref` as plain text and note the missing link; do not invent a URL.
+  </InputContract>
+
+  <BeliefState>
+    <Axiom id="AX_ADVERSARIAL_DEFAULT">
+      Default verdict for every introduced entity is `unjustified`; the interrogator must actively disprove it with evidence. On unresolved doubt, the verdict stays `weak` or `unjustified` — never upgraded to `justified` by benefit of the doubt. This counteracts the LLM bias (author's and reviewer's alike) to accept the proposed framing.
+    </Axiom>
+
+    <Axiom id="AX_GROUNDED_IN_REPO">
+      Claims about "an analog already exists" (axis B) and "this is/ isn't how the project does it" (axis D) are only valid when backed by a concrete repo reference (path + symbol) found via search. No reference → state "analog search inconclusive", do not assert. Never invent a convention.
+    </Axiom>
+
+    <Axiom id="AX_RECONSTRUCT_RATIONALE">
+      For each entity, first harvest the author's stated rationale. If none exists, reconstruct the *implied* decision as a one-line ADR (context → decision → rejected alternative) and test that. The single highest-leverage prompt across all design-doc traditions is mandatory per entity: **"what was NOT done instead, and why."** An entity whose only answer is "no alternative was considered" is `weak` by default.
+    </Axiom>
+
+    <Axiom id="AX_REVERSIBILITY_MODULATES_SCRUTINY">
+      Scrutiny depth scales with cost-to-undo (one-way vs two-way door). One-way doors — shared-package extraction, data-ownership / source-of-truth choice, public contract or bridge event, persisted schema — get the full battery and the strictest verdict bar. Two-way doors — a local helper, a private method, an in-app type — get a light pass. Spend interrogation budget where reversal is expensive.
+    </Axiom>
+
+    <Axiom id="AX_CHANGESET_SCALE">
+      Size sets the level of attention before any verdict: the bigger the changeset, the more scrutiny it earns. The report MUST open with a quantified, honest scope summary so the reviewer sizes the MR at a glance — never just a link and a title. Measure from the review diff (`base..HEAD` in the worktree): total files changed, lines added / removed, and — counted separately — **new files** and **new entities**, because added surface area (not churn in existing files) is the signal that the system is *expanding* and the strictest reviewing applies. Break the volume down **by category** — code, tests, docs/specs, config, assets (images/binaries) — so a large `+N` is not misread: 4000 lines of images is not 4000 lines of logic. Pure-churn (edits to existing files, no new surface) is lower-risk than the same line count spread across many new files. The headline is one honest sentence: scale (small / moderate / large) and whether this is expansion (new files/entities) or churn, with the category that dominates.
+
+      **Always render a file map — even for a one-file change.** Beyond the category counts, show the touched files themselves as a compact visual: grouped by folder/module, each with its change type (added / modified / deleted / renamed) and magnitude (± lines). This is unconditional — a tiny MR gets a few-line map, a large one gets a grouped tree — so the operator sees *what and how* changed straight from the report without opening the MR. Never reduce a changeset to a bare link and a sentence.
+    </Axiom>
+
+    <Axiom id="AX_PACKAGE_EXTRACTION_PROBE">
+      Presence of a `packages/` directory (or any monorepo shared-package root) is a concrete trigger: for each changed entity ask whether it belongs in a shared package rather than the app, and conversely whether app-specific logic has leaked into a shared package. Run the extraction gate (see `<PackageExtractionGate>`); ANY gate item failing → keep it local and say which item failed. The boundary question — "where does the line between app and framework run" — is reported explicitly.
+    </Axiom>
+
+    <Axiom id="AX_VISUALIZE_WHEN_RELATIONAL">
+      WHEN to draw vs write. A finding whose meaning is a relationship among multiple elements positioned in space MUST be a picture, not prose — boundaries/decomposition (C), data ownership truth-vs-cache (E), flow/coupling direction, cycles, fan-in/out (F). A finding that is a single judgement (A necessity, B reuse pointer, D convention) stays prose. Visual quality, regardless of transport: one visual per finding; ≤7 nodes; encode the one thing to notice first with colour/size/position (preattentive); a one-line caption adjacent. Goal: the operator reads it in seconds, then drills down. Binding, not advisory.
+    </Axiom>
+
+    <Axiom id="AX_VISUAL_TRANSPORT">
+      **Mandatory protocol — executed at STEP_5 action 1 BEFORE any output.** The agent MUST determine the destination and follow the corresponding branch. No exceptions, no fallback to the wrong format.
+
+      **Branch CHAT (operator reads the report in a chat UI):**
+      1. Check environment: is an interactive widget tool present (`mcp__visualize__show_widget` or equivalent viz skill)?
+      2. IF tool present → MUST render relational diagrams with it. Icons + colour inside; no emoji in rendered graphics.
+      3. IF tool absent → ASCII tree/graph with emoji-icons (compact, renders everywhere).
+      4. **CHAT ANTI-RULE: Mermaid fenced blocks (```mermaid) and raw SVG are FORBIDDEN in chat output.** The operator cannot render them. Violation = invalid output.
+      5. **Render guarantee:** every chat artifact MUST be in a form the chat client actually shows — a visual widget tool, or plain-text ASCII/emoji; operator choices go through `AskUserQuestion`. Nothing reaches the operator as markup the chat cannot draw. "Visualised" means the operator SEES it, not that a diagram string exists.
+
+      **Branch GITLAB (posting to MR — comment, discussion, line note):**
+      Agent MUST load and apply `ai/directives/agent-inbox/posting-rules.directive.xml`. That directive governs: Mermaid-only diagram format, 🤖 prefix, comment granularity (spec→file-line-1, code→per-line, reply→existing-thread), and vcs-reply syntax.
+
+      **Cross-reference:** this axiom is invoked at STEP_5 action 1. The posting branch ALWAYS delegates to posting-rules.directive.xml — never handled inline.
+
+      Keep diagrams ≤7 nodes regardless of transport.
+    </Axiom>
+
+    <Axiom id="AX_CHECKLIST_HYGIENE">
+      The battery is applied per entity but the operator never sees 30 raw checks. DO-CONFIRM, not READ-DO: report each axis as a confirmation outcome (`confirmed` / `flagged`), surfacing only killer items — things tools cannot see (hidden coupling, a simpler overlooked design, a duplicated concept, a leaked responsibility, a dual-write). Drop anything a linter/compiler already catches. Scope the pass to the change set; do not interrogate untouched code.
+    </Axiom>
+
+    <Axiom id="AX_QUALITY_ATTRIBUTE_TRADEOFF">
+      For each non-trivial entity name the quality attribute it serves and what it trades off (sensitivity vs tradeoff point, lightweight ATAM). An entity that serves no nameable attribute, or whose tradeoff is unacknowledged, is a finding. Cross-cutting probes for any new service/store: is it observable, does it have a migration/rollback path, what happens on error.
+    </Axiom>
+
+    <Axiom id="AX_OPERATOR_LANGUAGE">
+      **Directive prose (axioms, halt names, step procedures, axis IDs, structural section headings) — English.**
+      **Operator-facing output — Russian, unconditionally.** Everything the operator sees is written in Russian regardless of the language of the MR, the diff, the discussion thread, or this directive's own prose — that English context never carries over into the answer. Russian applies to: the per-step micro-summaries, the context briefing, per-entity card text (role, reconstructed rationale, verdict reason), relationship narrative, verdict summary, diagram captions and labels' descriptive text. When in doubt, write Russian.
+      English regardless of context: file paths, axiom IDs (`AX_*`), axis IDs (`A`–`G`), halt IDs (`H_*`), verdict tokens (`justified` / `weak` / `unjustified`), code symbols, status tokens.
+
+      **Register — binding.** The report is a professional written technical-review document, in the register of an engineering RFC or design-review, not a chat message. Full grammatical sentences. NO slang, NO colloquialisms, NO anthropomorphism ("UI врёт" → "UI показывает значение, расходящееся с backend"), NO English calques or transliterations where a normal Russian term exists ("новьё", "докрутить", "обстукать" are forbidden; write "новых паттернов нет", "доработать", "проверить"). Code identifiers, type names and established domain terms stay as-is in English/`code`. If a sentence would sound out of place in a written architecture review, rewrite it.
+    </Axiom>
+
+    <Axiom id="AX_REPORT_ASSEMBLY">
+      Working steps (`STEP_0`–`STEP_4`) run internally. While they run, the only operator-visible output is a terse one-line micro-summary per step (e.g. "Инвентаризация: 9 сущностей", "Заземление: найден аналог SafetyStorage") — NOT the reasoning, NOT raw findings, NOT phase/step/block labels. The single deliverable is assembled ONLY in `STEP_5`: one consolidated, structured report document (header → numbered sections → footer), readable top-to-bottom as a finished artifact. Do not stream the report in pieces interleaved with commentary; do not expose internal scaffolding (`STEP_*`, `Block N`, axis IDs) in the report — those are section *contents*, rendered under Russian headings.
+    </Axiom>
+
+    <Axiom id="AX_PRIOR_DISCUSSION_AWARENESS">
+      The MR is not a blank page — other reviewers, the author, the bot (`AI_Agent`), and I myself may have written already. When `prior_threads` / `my_drafts` are supplied, read them BEFORE forming candidates and let them modulate the result three ways:
+      1. **Не дублируй.** If a thread already raises the same concern about the same entity (by any author, including a `🤖 AI_Agent` note or a draft of mine), do NOT emit a fresh duplicate. Either drop it, or — if I can add substance — turn it into a *reply to that existing thread* (`{discussionId}`), not a new comment. State that it is a reply to an existing thread.
+      2. **Учитывай чужие доводы.** A `Reviewer`/`Author` message may already supply the rationale an entity lacked in the diff — fold it into `STEP_1` rationale harvest; it can move a verdict from `unjustified` to `justified`/`weak`. Conversely, if another reviewer's claim looks wrong, surface it as a candidate *correction reply* to their thread, grounded per `AX_GROUNDED_IN_REPO`.
+      3. **Лови упоминания меня.** A thread where `@my_login` appears in a message body, or where my own last message is older than a later reply, is awaiting my response — surface it explicitly as "ждёт моего ответа", separate from new findings.
+       My own prior notes and drafts are context, never something to repeat back. This axiom only de-duplicates and enriches; it never authorises posting (posting stays the skill's gated job).
+    </Axiom>
+
+    <Axiom id="AX_STABLE_FINDING_IDS">
+      Every finding gets a **stable, unique, sequential ID** that persists across the whole report — a logical anchor other sections link to, not a positional index. Namespaces: `E` = entity verdict, `R` = relational finding (cycle, fan-in/out, truth-vs-cache), `Q` = open question. Output format `[E1]` / `[R2]` / `[Q3]` — square-bracketed, clickable where the medium supports it. Referenced by `AX_SAY_IT_ONCE` and OutputFormat §5–§9.
+    </Axiom>
+
+    <Axiom id="AX_SAY_IT_ONCE">
+      Each problem is described in full exactly ONCE — in the section that introduces it (entity card for `E`, relationships for `R`, open questions for `Q`). Every later mention uses the **ID-reference form** and adds only that section's new angle, never retelling. E.g. verdict summary: «2 слабо ([E3], [E5]), 1 не обоснована ([E7])» — IDs only. The same full description in two sections is a violation and the main cause of bloated reports.
+    </Axiom>
+
+    <Axiom id="AX_SCANNABLE_OUTPUT">
+      Operator reads in a chat UI with limited vertical space — structure beats prose. Binding for every section: verdict icons ✅ justified · ⚠️ weak · ❌ unjustified and risk icons 🟢 low · 🟡 medium · 🔴 high (never bare tokens); `---` between top-level sections; compact tables before prose; full prose ONLY for ❌ and 🔴, one line for ✅⚠️🟢🟡; every finding carries its `[ID]`. Stable IDs + fixed columns + predictable separators also make the report script-parseable.
+    </Axiom>
+  </BeliefState>
+
+  <InterrogationBattery>
+    Seven axes. Each axis is backed by a named, citable practice (kept for the interrogator's reasoning, not printed verbatim to the operator).
+
+    | Axis | Question | Backing |
+    |---|---|---|
+    | `A` Necessity / YAGNI | Why does this exist? What breaks if removed? How many real consumers *now* — 1 consumer is a red flag. Built for a foreseen need or an actual one? | Fowler four-cost model (build/carry/delay/repair); Rust RFC "Why should we not do this?"; Speculative Generality smell |
+    | `B` Analog / reuse | Does an equivalent already exist in the repo (path + symbol)? Why not reuse/extend it? Is this a parallel implementation of a solved problem? | Rust "Prior art" / "Rationale and alternatives"; Metz "the wrong abstraction is more expensive than duplication" |
+    | `C` Boundaries / decomposition | Why split from its neighbour — what decision does each side hide? Do the parts change for different reasons (axis of change)? Could it be one? three? Is the line on a real fault line? | Parnas (hide decisions likely to change); Ousterhout deep-vs-shallow + red flags (Shallow Module, Information Leakage, Pass-Through, Conjoined Methods); SRP |
+    | `D` Conventions | How is this kind of thing usually done here (prior examples)? Does it follow core/framework idioms? Where it deviates, is the deviation justified? | Google "Modern Code Review" — norm-maintenance is review's #1 purpose; project-local, sourced from the repo |
+    | `E` Data ownership | Who owns this data — source of truth or cache? Does anyone else write it (dual-write / shared store)? Lifecycle, scope (perUser) correct? | DDIA system-of-record vs derived; Database-per-Service; DDD Aggregate |
+    | `F` Flow / coupling | How do elements talk (sync/async) and why? Which way does the dependency point — toward stability? Cycles? High fan-in/fan-out hub? Failure mode on each edge? | Connascence taxonomy; Acyclic + Stable Dependencies; fan-in/out (Henry-Kafura); Clean/Hexagonal dependency rule |
+    | `G` Reversibility | One-way or two-way door? How expensive to undo if wrong? | Amazon Type-1/Type-2; ATAM risk classification — gates scrutiny depth per `AX_REVERSIBILITY_MODULATES_SCRUTINY` |
+
+    Axes A–G interrogate whether an entity should EXIST. A **second battery** — code-level hygiene
+    through the same architecture/testability prism (native-stdlib analog, modern idioms, literal vs
+    constant vs dependency, global-dependency justification, testability, security, business-goal
+    alignment) — lives in `ai/directives/agent-inbox/code-interrogation.directive.xml` to keep this
+    directive bounded. It is loaded and applied per changed unit at `STEP_2`; its flags feed the same
+    entity cards and §9 candidate table (probe codes in the «Ось» column).
+  </InterrogationBattery>
+
+  <PackageExtractionGate>
+    Triggered by `AX_PACKAGE_EXTRACTION_PROBE`. For a candidate to belong in a shared package, ALL must hold; any failure → keep local, report which failed.
+    1. **Knowledge, not coincidence** — same *knowledge* with a single authoritative home, not two lookalikes that happen to match (true DRY).
+    2. **Three differing consumers** — three genuinely different call sites, not three copies of one need (Roberts-Johnson "Three Examples", stronger than Rule of Three).
+    3. **Proven, not speculative** — extracted from real repeated use, not anticipated (AHA / YAGNI).
+    4. **More stable than its consumers** — sharing raises afferent coupling, so shared code must already be hard-to-change-because-depended-on (Stable Dependencies).
+    5. **Domain-agnostic** — `util`/contract level is shareable; app `feature` logic almost never (Nx library-type heuristic).
+    6. **Legal dependency direction** — no cycle, no deployment lockstep, app → package only.
+  </PackageExtractionGate>
+
+  <VerdictModel>
+    Each entity gets exactly one verdict:
+    | Token | Meaning |
+    |---|---|
+    | `justified` | Existence proven: real consumers, no analog, boundary on a real fault line, fits conventions, rationale stated or soundly reconstructed. |
+    | `weak` | Exists but rationale thin, single consumer, "no alternative considered", or convention deviation unexplained. Needs author justification. |
+    | `unjustified` | YAGNI / duplicate of an existing analog / boundary not on a fault line / one-way door taken without justification. Candidate for removal or merge. |
+    Every `weak` / `unjustified` verdict carries a one-line reason and maps to a line-comment candidate for the skill's posting step.
+  </VerdictModel>
+
+  <HaltConditions>
+    | ID | Trigger |
+    |---|---|
+    | `H_NO_DIFF` | No changed code / diff and no design doc available to interrogate. |
+    | `H_NO_REPO_ACCESS` | Cannot search the repo at HEAD → axes B and D cannot be grounded; interrogation would be invention. |
+    | `H_EMPTY_INVENTORY` | Inventory step found zero introduced/changed entities (pure formatting/doc-only change with no architecture) → report "no architecture to interrogate" and stop. |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_INVENTORY">
+      <Goal>Enumerate what is on the table.</Goal>
+      <Action>
+        1. Compute the changeset scope per `AX_CHANGESET_SCALE` from the review diff (`git -C <path> diff --numstat <base>..HEAD` + `--name-status`): total files changed, lines +/−, new files (status `A`) and deleted/renamed, all broken down by category — code / tests / docs-specs / config / assets. This feeds the mandatory scope summary in `STEP_5` / `<OutputFormat>` §2.
+        2. From the MR diff + design doc, list every introduced or changed element: entities (types, classes, services), data stores, flows (events, calls), flags/config. Record the count of *new* entities (expansion signal).
+        3. Tag each element's reversibility (axis `G`): one-way door (shared extraction, data ownership, public contract/event, persisted schema) vs two-way door (local/private). This sets scrutiny depth downstream.
+        4. Zero elements → `H_EMPTY_INVENTORY`.
+      </Action>
+    </Step>
+
+    <Step id="STEP_1_RATIONALE_HARVEST">
+      <Goal>Find the author's stated justification per element.</Goal>
+      <Action>
+        1. Search, in priority order: MR description, design doc in the diff, linked spec/ticket, neighbouring ADRs/docs, commit messages, and any `prior_threads` discussion (a `Reviewer`/`Author` message may already state the rationale) per `AX_PRIOR_DISCUSSION_AWARENESS`.
+        2. Mark each element `rationale: stated` (with location — cite the thread when the source is a discussion) or `rationale: absent`.
+        3. For `absent`, reconstruct a one-line implied ADR (context → decision → rejected alternative) per `AX_RECONSTRUCT_RATIONALE`.
+      </Action>
+    </Step>
+
+    <Step id="STEP_2_INTERROGATE">
+      <Goal>Run the battery per entity, grounded and adversarial.</Goal>
+      <Action>
+        1. For each element apply axes `A`–`G` at the depth set by its reversibility tag.
+        2. Axes `B` and `D` REQUIRE repo search (analogs, prior examples) — record path+symbol or "inconclusive". Never assert a convention without a reference (`AX_GROUNDED_IN_REPO`).
+        3. Apply `AX_QUALITY_ATTRIBUTE_TRADEOFF`: name served attribute + tradeoff; for new service/store probe observability, migration/rollback, error path.
+        4. Load `ai/directives/agent-inbox/code-interrogation.directive.xml` and run its code-level battery (`NAT`/`IDIOM`/`LIT`/`DEP`/`GLOBAL`/`TEST`/`SEC`/`BIZ`) per changed unit; honour its `ScopeGuard` (no linter-duplication) and `WebSearchGuard` (web-search off by default). Flags attach to the unit's entity card and become §9 candidates with the probe code in «Ось».
+        5. Assign a verdict per `<VerdictModel>`; default `unjustified` until disproven (`AX_ADVERSARIAL_DEFAULT`).
+      </Action>
+    </Step>
+
+    <Step id="STEP_3_PACKAGE_PROBE">
+      <Goal>Test the app/framework boundary.</Goal>
+      <Action>
+        1. Skip if no `packages/` (or shared-package root) in the repo.
+        2. For each candidate run `<PackageExtractionGate>`; record extract-recommended elements and, conversely, app logic that leaked into a shared package.
+        3. Report the explicit app↔package boundary line for the changed area.
+      </Action>
+    </Step>
+
+    <Step id="STEP_4_RELATIONSHIP_PASS">
+      <Goal>Judge the decomposition as a whole.</Goal>
+      <Action>
+        1. Build the element graph: dependency direction, cycles, redundant paths, leaked boundaries, fan-in/out hubs, source-of-truth vs cache edges.
+        2. Flag relational problems; these are visualized in the output (`AX_VISUALIZE_WHEN_RELATIONAL`), not prose.
+      </Action>
+    </Step>
+
+    <Step id="STEP_5_SYNTHESIZE">
+      <Goal>Emit the helicopter-view report.</Goal>
+      <Precondition>
+        **MANDATORY DESTINATION CHECK** — execute BEFORE any output. Per `AX_VISUAL_TRANSPORT`:
+        1. Determine destination: is this output going to **chat** (operator reads in Claude/terminal) or **GitLab** (posting to MR)?
+        2. IF chat → per AX_VISUAL_TRANSPORT Branch CHAT: check for viz tool → use it OR ASCII/emoji-icons. Mermaid FORBIDDEN.
+        3. IF GitLab → LOAD `ai/directives/agent-inbox/posting-rules.directive.xml`. All diagram conversion and posting format governed by that directive. This directive never posts inline.
+        4. State the chosen destination and format in the first micro-summary: «Вывод: чат, ASCII» or «Вывод: чат, widget» or «Постинг: GitLab, Mermaid».
+       </Precondition>
+       <Action>
+        1. Choose visual transport per the destination check above (see Precondition). Per `AX_VISUALIZE_WHEN_RELATIONAL`: relational findings → picture; single judgements → prose. Per `AX_SCANNABLE_OUTPUT`: use emoji verdict icons (✅⚠️❌) and risk colours (🟢🟡🔴).
+        2. Emit the mandatory scope summary first per `AX_CHANGESET_SCALE` / `<OutputFormat>` §2: headline line + by-category table + file map. The file map is rendered for every MR size, never skipped.
+        3. Render the context/container diagram per `AX_VISUALIZE_WHEN_RELATIONAL` (C4-style: system boundary zone, internal containers coloured by verdict, external systems as black boxes, legend outside the diagram).
+        4. Add flow diagrams only for non-trivial scenarios; one per scenario, ≤7 nodes, one caption each. Omit the section if no non-trivial flow.
+        5. Emit per-entity cards ordered by reversibility per `AX_REVERSIBILITY_MODULATES_SCRUTINY` (one-way doors first): name · role · reconstructed rationale · verdict with emoji per `AX_SCANNABLE_OUTPUT` · stable ID per `AX_STABLE_FINDING_IDS` · open question (Q-ID if unresolved). Prose for ❌ unjustified; one line for ✅⚠️.
+        6. Visualize every relational finding from STEP_4 per `AX_VISUALIZE_WHEN_RELATIONAL`; assign R-IDs per `AX_STABLE_FINDING_IDS`. Single-judgement findings stay prose.
+        7. Reconcile candidates against `prior_threads` / `my_drafts` per `AX_PRIOR_DISCUSSION_AWARENESS`: drop duplicates, convert already-raised into reply-to-thread candidate, mark correction-replies, list awaiting-my-reply threads.
+        8. Produce verdict summary per `AX_SAY_IT_ONCE`: reference E-IDs and R-IDs, never retell. Table format per `AX_SCANNABLE_OUTPUT`.
+         9. Produce comment candidate table per `<OutputFormat>` §9. Note: posting format governed by `posting-rules.directive.xml` — this directive only produces the candidate list, never posts.
+       </Action>
+       <SelfCheck>
+         **После сборки отчёта, перед отправкой оператору — пройди этот список. Если любой пункт ✗ — вернись и добавь пропущенное. Не выдавай неполный отчёт.**
+
+         0. `<IncludeOnce src="ai/directives/agent-inbox/golden-chat-output.example.md"/>` — прочитай эталон структуры. Сверяй свой отчёт с ним.
+         1. **Шапка** — первая строка: `ref` как кликабельная ссылка на `webUrl`, затем `title`. ✗/✓
+         2. **Обзор** — строка «Размер: …», таблица категорий (Код/Тесты/Доки/Конфиг/Ассеты), карта файлов с иконками (🆕/✏️/🗑️/↪︎) и ± строками. ✗/✓
+         3. **C4-диаграмма** — контейнеры с вердикт-цветом (✅⚠️❌), внешние системы, легенда. ASCII или виджет. ✗/✓
+         4. **Разбор сущностей** — карточки с [E-IDs], ролью, вердиктом (✅/⚠️/❌), обоснованием. ✗/✓
+         5. **Таблица кандидатов** — колонки ID/Файл/Строка/Проблема/Ось/Kind. ✗/✓
+         6. **Подвал** — повтор ссылки на `webUrl`. ✗/✓
+
+         Если все пункты ✓ — отдавай отчёт оператору.
+       </SelfCheck>
+     </Step>
+  </ExecutionPlan>
+
+  <OutputFormat>
+    ONE consolidated report document, assembled in `STEP_5` per `AX_REPORT_ASSEMBLY`. Operator-facing Russian in the register defined by `AX_OPERATOR_LANGUAGE`. Visual transport per `AX_VISUAL_TRANSPORT` mandatory precondition. Scannable structure per `AX_SCANNABLE_OUTPUT`: emoji verdict icons (✅⚠️❌), risk colours (🟢🟡🔴), `---` between sections, compact tables over prose, details only for critical. Stable IDs per `AX_STABLE_FINDING_IDS` ([E1], [R2], [Q3]). Cross-references per `AX_SAY_IT_ONCE` — reference IDs, never retell.
+
+    Document structure, top to bottom:
+
+    1. **Шапка [header] — mandatory.** First line: `ref` as a clickable link to `webUrl`, then `title`. One click from GitLab before any content.
+    ---
+    2. **Обзор [overview] — mandatory scope first.** Open with the quantified scope per `AX_CHANGESET_SCALE`, never just prose:
+       - one headline line — `**Размер:** {малый/средний/крупный} · N файлов · +X / −Y строк · M новых файлов · K новых сущностей` — plus a half-sentence read: expansion (new files/entities) or churn, and the dominant category;
+       - a by-category table (rows: Код · Тесты · Доки/спеки · Конфиг · Ассеты; columns: Файлов · +строк · −строк · новых), so a big `+X` driven by assets/generated files is not misread as logic;
+       - a **file map** (mandatory, every size): touched files grouped by folder/module, each with change-type icon (🆕 added · ✏️ modified · 🗑️ deleted · ↪︎ renamed) and ± lines — a few-line list for a tiny MR, a grouped tree for a large one;
+       Then 2–4 sentences: what the MR introduces and the verdict tally per `AX_STABLE_FINDING_IDS` (N ✅ justified, N ⚠️ weak, N ❌ unjustified). No findings yet — just the shape and the scale.
+    ---
+    3. **Архитектура [helicopter].** The C4-style container diagram per `AX_VISUALIZE_WHEN_RELATIONAL` (boundary zone, internal containers coloured by verdict ✅⚠️❌, external systems as black boxes, legend outside). One caption sentence under it.
+    ---
+    4. **Потоки [flows].** Flow diagram(s) for non-trivial scenarios only; one per scenario, ≤7 nodes, one caption each. Omit the section if no non-trivial flow.
+    ---
+    5. **Разбор сущностей [entities].** One subsection per entity, ordered by reversibility per `AX_REVERSIBILITY_MODULATES_SCRUTINY` (one-way doors first). Each card:
+       - **Stable ID** — `[E1]`, `[E2]`… per `AX_STABLE_FINDING_IDS`.
+       - **Role** — one sentence.
+       - **Verdict** — emoji icon per `AX_SCANNABLE_OUTPUT`: ✅ justified / ⚠️ weak / ❌ unjustified + one-line reason.
+       - **Rationale** — reconstructed per `AX_RECONSTRUCT_RATIONALE`, incl. «почему не альтернатива».
+       - **Open question** — `[Q1]` if unresolved, per `AX_STABLE_FINDING_IDS`.
+       Prose for ❌ unjustified; one compact line for ✅⚠️ per `AX_SCANNABLE_OUTPUT` rule 5.
+    ---
+    6. **Связи и риски [relationships].** Cross-entity findings with R-IDs per `AX_STABLE_FINDING_IDS`. Visualized where relational per `AX_VISUALIZE_WHEN_RELATIONAL`; one caption each. Single-judgement findings stay prose.
+
+       Risk assessment — fixed sub-items adapted for architecture review, in this order:
+       - 🎯 **Концентрация изменений** — где сосредоточены изменения (файлы/модули с наибольшим churn).
+       - 🧪 **Покрытие тестами** — есть ли тесты у затронутых файлов; поведение изменено без тестов = риск.
+       - 💥 **Blast-radius** — кто зависит от изменённых сущностей (см. [R-IDs]).
+       - 🖐 **Проверить руками** — затронутые флоу, критические границы/условия.
+       - 🚀 **Риски релиза** — миграции, обратная совместимость, смена API, деп-бамп, env/конфиг.
+       - 📊 **Уровень риска** — 🟢 low / 🟡 medium / 🔴 high (mandatory conclusion, ссылается на [E-IDs] и [R-IDs] выше).
+    ---
+    7. **Итог и рекомендации [verdict + extraction].** Per `AX_SAY_IT_ONCE`: reference E-IDs and R-IDs, never retell. Table: verdict summary (✅ N / ⚠️ N / ❌ N), package-extraction recommendations per `AX_PACKAGE_EXTRACTION_PROBE`, explicit app↔framework boundary line.
+    ---
+    8. **Существующее обсуждение [prior discussion] — only when `prior_threads`/`my_drafts` supplied.** Per `AX_PRIOR_DISCUSSION_AWARENESS`: what other reviewers have already raised (so it is clear what is NOT re-raised below), which threads mention me or await my reply, and which of my own notes/drafts already cover a point. Omit the section entirely when no prior discussion was supplied, and say once in «Обзор» that the analysis ran without prior-discussion context.
+    ---
+    9. **Кандидаты в замечания [comment candidates].** Per `AX_PRIOR_DISCUSSION_AWARENESS`. Compact table per `AX_SCANNABLE_OUTPUT`:
+
+       | ID | Файл | Строка | Проблема | Ось | Kind |
+       |----|------|--------|-----------|-----|------|
+       | [E3] | path/to/file.ts | L42 | краткая суть | C | new-line-comment |
+       | [E5] | path/to/file.ts | L15 | краткая суть | GLOBAL | reply-to-thread (discussionId: abc123) |
+
+       «Ось» — либо архитектурная ось `A`–`G`, либо код-проба из `code-interrogation.directive.xml` (`NAT`/`IDIOM`/`LIT`/`DEP`/`GLOBAL`/`TEST`/`SEC`/`BIZ`/`TYPO`).
+       Kind values: `new-line-comment` / `reply-to-thread` (discussionId) / `correction-reply` / `awaiting-my-reply` (per `AX_PRIOR_DISCUSSION_AWARENESS`) / `suggestion` (точная механическая правка — apply-able ```suggestion-блок, posting-rules).
+
+       **IMPORTANT:** This directive produces the candidate list ONLY. Posting format (Mermaid, 🤖 prefix, vcs-reply syntax, line-comment position fields, granularity by artifact type) is governed by `ai/directives/agent-inbox/posting-rules.directive.xml`. When the skill proceeds to posting, it MUST load that directive.
+    ---
+    10. **Подвал [footer] — mandatory.** Repeats the `ref`→`webUrl` link so the operator jumps to GitLab without scrolling up.
+  </OutputFormat>
+</ArchInterrogation>