gennady 0.8.3 → 0.8.4-draft.2

package/dist/ai/directives/sdd-v2/interface.directive.xml

@@ -0,0 +1,277 @@
+<SddInterface keywords="interface, schema, versioning, compatibility, consumer, decision-log, sdd-interface" type="directive" ver="2.1">
+  <Mission>
+    Author or evolve an `interface` scope spec — cross-scope interfaces: schema (OpenAPI / gRPC proto
+    / JSON Schema / GraphQL), versioning policy, compatibility matrix, consumer declaration. A
+    self-contained living spec. Loaded lazily by the router; inherits the router core (language,
+    dialogue, safeguard, diverge, no-narration, stateless) — not repeated here.
+
+    Input — scope name + intent (or an existing spec for refine / pivot). Output —
+    `specs/<scope>/<scope>.spec.md` (scope-type interface).
+
+    Out of scope: implementation, module decomposition, product / library design. The project portal
+    is the root branch.
+
+    **Glossary.** Modes: greenfield · refine · pivot · rewrite. Consumers = the scopes that depend on this
+    interface scope.
+  </Mission>
+
+  <BeliefState deps="AX_OPERATOR_LANGUAGE, AX_OPERATOR_DIALOGUE_STYLE, AX_DIALOGUE_DISCIPLINE, AX_OPERATOR_SAFEGUARD, AX_DIVERGE_BEFORE_RECOMMEND, AX_NO_PROCESS_NARRATION, AX_STATELESS_ARTIFACT, AX_SCALE_PROPORTIONAL_DEPTH">
+    <Axiom id="AX_DIRECTIVE_MODE">
+      Each directive runs in one of several modes, auto-detected from operator intake. Mode controls
+      step branching and which axioms apply. The concrete mode set is directive-specific
+      (e.g. `greenfield` / `refine` / `pivot`; `initial` / `extend-dag`; `initial` / `add-module` / `refine-module`).
+    </Axiom>
+
+    <Axiom id="AX_MODE_AUTO_DETECT_OR_HALT">
+      Mode detection is mechanical and table-driven from intake (artifact presence + operator verb).
+      Ambiguous intake never defaults silently → HALT and ask the operator (binary disambiguation
+      where possible). The detection table is directive-specific.
+    </Axiom>
+
+    <Axiom id="AX_PORTAL_READ_ONLY_WITH_PLACEHOLDER_EXCEPTION">
+      The `scope` flow reads `specs/README.md` for project context (vision, scope graph, sibling scopes). It MUST NOT rewrite the file. The narrow exception (per the `root` flow's `AX_PORTAL_PRIMARY_OWNER`): when the `scope` flow creates a brand-new scope, it MAY append one placeholder row to the Scopes table tagged `🚧 (awaiting root sync)`. Any other edit is forbidden — run the `root` flow instead.
+    </Axiom>
+
+    <Axiom id="AX_LIVING_SPEC">
+      The scope spec is a living document. In `refine` mode any section may be updated in place. There is no frozen 7 Handoff — the Handoff section evolves as modules are added.
+
+      `pivot` uses Decision Log supersession: the old entry → `status: superseded`, body preserved; the new entry carries `Supersedes: D-NNN` and `Was → Now`. The spec body is rewritten in place; git history is the full predecessor.
+    </Axiom>
+
+    <Axiom id="AX_SPEC_LIFECYCLE">
+      A spec lives in two states. **master** — clean file (no Change Manifest, no marks), the target on the main branch. **review-state** — the same file on a working branch during a change: the target text is written IN PLACE (everything else byte-for-byte, so the branch diff reads like a normal PR), with a temporary `CHANGE_MANIFEST` (`CHANGE_MANIFEST_FORMAT`) at the top and affected lines marked `✚` (new) / `~` (changed). New IDs are appended to the end of their section; existing IDs are never renumbered.
+
+      `greenfield` (∅ → review-state): the first version is written directly as review-state with `ТИП: greenfield` and NO per-line marks (everything is new — the diff against an empty file already shows it). `refine` / `pivot` edit an existing master in place WITH marks.
+
+      The spec change is a reviewable PR (design-PR): the internal critic loop runs first (necessary but NOT sufficient), then the diff goes to EXTERNAL review and the session waits. **compress** (review-state → master) fires ONLY when external review approves — the operator says «no comments» — NOT on internal-critic CLEAN and NOT on a timer. On approval: remove the `CHANGE_MANIFEST` whole, strip the `✚`/`~` marks (lines stay), resolve any ID collisions in one commit, and for `pivot` mark superseded decisions; then merge. Implementation (scaffold → execute) follows the merged master — the design is approved before it is built.
+
+      A spec MUST NOT be left in review-state once its change is closed — that is drift the tools track (`sdd-check`): a malformed review-state or a manifest lingering past its lifetime is surfaced with the reason, so the agent fixes it or escalates.
+    </Axiom>
+
+    <Axiom id="AX_SPEC_IS_SOLE_SOURCE">
+      Phase reads specs only, never code; no project-wide search (grep / find / ripgrep)
+      outside the reads explicitly listed by the directive. `audit` is the only directive
+      permitted to read code; it alone resolves spec/code mismatch.
+    </Axiom>
+
+    <Axiom id="AX_INTERFACE_FLOW">
+      For scope-type=interface:
+      - Interface Declaration: schema format (OpenAPI / gRPC proto / JSON Schema / GraphQL), versioning scheme (semver / date-based / none), namespacing.
+      - Compatibility Matrix: backward-compat guarantees, breaking-change protocol.
+      - Consumer declaration: which scopes consume this interface scope.
+    </Axiom>
+
+    <Axiom id="AX_DECISION_LOG_REQUIRED">
+      Every non-trivial decision → a Decision Log entry in `DECISION_LOG_ENTRY_FORMAT`
+      (D-NNN, Status, Recorded, Why in the operator's wording, Risk accepted, Rejected
+      alternatives; IDs are stable). Which decisions qualify and which Decision Log receives
+      the entry are specified per directive.
+    </Axiom>
+
+    <Axiom id="AX_PIVOT_REQUIRES_SUPERSESSION">
+      In `pivot` mode every replaced decision: the old D-NNN → `status: superseded`. The new D-NNN carries `Was → Now` + `Supersedes: D-NNN` + a git ref pointing to the pre-rework state. Pivot Invalidation List enumerates downstream artifacts requiring `refine-module` / reopen — consumed by `audit` via `AX_STALE_AFTER_PIVOT_VERIFICATION`.
+
+      `rewrite` mode is the exception: a pre-production / v0 scope with no production backing, whose old content was scratch that helps nothing going forward. It replaces the spec from a clean slate — NO supersession trail, NO Pivot Invalidation List (nothing downstream to keep coherent; git history is the only record). Use `pivot` (keep the trail) whenever the scope has any production backing or downstream consumers; use `rewrite` only for genuine v0 throwaway. Enforcement: a scope that already has downstream artifacts on disk (module specs or task tickets) is by definition NOT v0 — `rewrite` is forbidden there; halt and use `pivot`.
+    </Axiom>
+
+    <Axiom id="AX_CROSS_SCOPE_DEPENDENCIES">
+      Scope spec declares `depends-on` edges in Scope Dependencies. These edges feed cascade computation in the `scaffold` flow. Cross-scope contracts are sourced from `interface`-type scopes — never described inside a product scope spec.
+    </Axiom>
+
+    <Axiom id="AX_EVIDENCE_HYGIENE">
+      Separate Facts / Assumptions / Hypotheses in every intake-style frame.
+      - **Facts** — directly observable from input artifacts (spec, sibling specs, rule files, extracted measurements).
+      - **Assumptions** — working assumptions awaiting confirmation; mark explicitly.
+      - **Hypotheses** — conjectures that require operator validation before they are promoted to requirements.
+
+      Conflating the three causes downstream decisions to be made on unvalidated assumptions, producing requirements mismatches that surface only at integration; surface them in distinct lists.
+    </Axiom>
+
+    <Axiom id="AX_BOOTSTRAP_NARROW_READ">
+      Discovery is design-blind to repository code (per `AX_SPEC_IS_SOLE_SOURCE`) **except** inside STEP_7 (External Dependencies Audit), where narrow Read is permitted **only for inventory verification** — confirming whether a referenced package, file, scope, or tool physically exists.
+      Permitted reads in STEP_7: `package.json` and equivalents, `tsconfig.json` and equivalents, `specs/README.md`, sibling scope manifests, filesystem existence checks.
+      Forbidden in STEP_7: reading application source code to influence design decisions; revisiting Vision / Requirements / Architecture / Contracts based on what was found. If a finding genuinely invalidates a design decision, pop back to the relevant STEP_3–STEP_6 explicitly and treat as `pivot`.
+    </Axiom>
+
+    <Axiom id="AX_SPEC_MANDATORY_DIAGRAM">
+      Every interface spec carries at least one diagram in an `Overview` section, high up — who produces vs consumes the contract, or the version-transition flow, at a glance. The floor is one (mermaid or ASCII), held by tooling: `sdd-check` fails a missing section (`SDD_NO_DIAGRAM_BLOCK`) or an empty one (`SDD_DIAGRAM_BLOCK_EMPTY`). Beyond the floor the author adds more views by judgment; that is not a gate.
+    </Axiom>
+
+    <Axiom id="AX_ARTIFACT_STYLE_SELF_CHECK">
+      Before writing any operator-facing artifact, recall the language rules —
+      `AX_OPERATOR_DIALOGUE_STYLE` (bureaucratic noun-for-verb phrasing, literal calque, bookish word)
+      and `AX_READER_WITHOUT_SESSION_CONTEXT` (a branch name, «как обсуждали», a session-plan label) —
+      and hold the text about to be written to them. This is the author's own pass, done in the moment
+      of writing, not a report to the operator. The independent post-check (lint, audit) stays separate
+      and unchanged — this pass does not replace it.
+    </Axiom>
+
+    <Axiom id="AX_CLOSE_WITH_INTEGRITY_CHECK">
+      A mutation is not done until its scope passes the mechanical check. Any flow that creates or evolves an artifact under a scope — spec, module, ticket, DAG, tracker — closes by running `sdd-check` on the affected scope (`sdd-check --all specs/<scope>`; portal, task-DAG, tracker, or cross-scope work → `sdd-check --all .`) and resolving or consciously deferring every finding before handing off.
+    </Axiom>
+  </BeliefState>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_NO_INTAKE` | Empty intake |
+    | `H_AMBIGUOUS_MODE` | Spec exists + mode verb absent (per `AX_MODE_AUTO_DETECT_OR_HALT`) |
+    | `H_BREAKING_CHANGE_NO_PROTOCOL` | A breaking interface change without a declared breaking-change protocol |
+    | `H_PIVOT_NO_INVALIDATION_LIST` | `pivot` mode without a Pivot Invalidation List |
+    | `H_REWRITE_WITH_DOWNSTREAM` | `rewrite` mode but the scope already has tickets — not v0, use `pivot` (`AX_PIVOT_REQUIRES_SUPERSESSION`) |
+    | `H_BOOTSTRAP_REQUIREMENTS_MISSING` | External-deps step finished without a Bootstrap Requirements section |
+    | `H_OPERATOR_REJECT` | Operator rejected the spec |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_0_INTAKE">
+      <Goal>Resolve scope name and mode.</Goal>
+      <Action>
+        State from the router gives the portal + scope-type (interface). Resolve the scope name; stat
+        the spec → `greenfield` or detect the mode per `AX_DIRECTIVE_MODE` / `AX_MODE_AUTO_DETECT_OR_HALT`.
+      </Action>
+    </Step>
+    <Step id="STEP_1_CONFIRM">
+      <Goal>Confirm interface and outline the section set.</Goal>
+      <Action>Confirm scope-type, outline sections. Approval Check. STOP.</Action>
+    </Step>
+    <Step id="STEP_2_INTERFACE_DECLARATION">
+      <Goal>Declare the interface.</Goal>
+      <Action>
+        Per `AX_INTERFACE_FLOW`: schema format (OpenAPI / gRPC proto / JSON Schema / GraphQL),
+        versioning scheme (semver / date-based / none), namespacing — Facts / Assumptions /
+        Hypotheses separated per `AX_EVIDENCE_HYGIENE`. Then run the operator interview —
+        `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/interview-protocol.directive.xml")` — passing
+        scope-type `interface` (selects the TopicCatalog block) and the confirmed `scale:` from
+        the session file: per `AX_SCALE_PROPORTIONAL_DEPTH` `fix` / `function` → base topics + the
+        triage minimum; `product` → the full scope-type block. The interview IS the substance of
+        the step. Approval Check. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_3_VERSIONING_POLICY">
+      <Goal>Lock the versioning policy.</Goal>
+      <Action>
+        Versioning scheme + breaking-change protocol + consumer-notification rule — each locked choice
+        recorded as a Decision Log entry (`AX_DECISION_LOG_REQUIRED`). A breaking change
+        without a protocol → `H_BREAKING_CHANGE_NO_PROTOCOL`. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_4_COMPATIBILITY_MATRIX">
+      <Goal>Lock compatibility guarantees and consumers.</Goal>
+      <Action>
+        Backward-compat guarantees + consumer declaration (which scopes consume this contract, per
+        `AX_CROSS_SCOPE_DEPENDENCIES`). STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_5_EXTERNAL_DEPENDENCIES_AUDIT">
+      <Goal>Materialize Bootstrap Requirements.</Goal>
+      <Action>
+        Walk the drafted spec; extract external assumptions; classify `exists` | `missing` | `unknown`
+        (narrow read for inventory only, per `AX_BOOTSTRAP_NARROW_READ` and `AX_SPEC_IS_SOLE_SOURCE` —
+        design stays sourced from specs); resolve with the operator;
+        materialize the Bootstrap Requirements table. Empty only if explicit «nothing to bootstrap»,
+        else `H_BOOTSTRAP_REQUIREMENTS_MISSING`.
+      </Action>
+    </Step>
+    <Step id="STEP_6_FINAL_SPEC">
+      <Goal>Emit the interface spec.</Goal>
+      <Action>
+        In `greenfield`/`rewrite` mode, when `specs/<scope>/<scope>.spec.md` does not exist yet,
+        create its skeleton via `sdd-new interface --scope <scope>` — it never overwrites and prints
+        the section manifest (which sections are REQUIRED and what to fill); in `refine`/`pivot` mode
+        the file already exists, edit it in place, skip `sdd-new`. Content guidance per
+        `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/interface-spec-structure.xml")`.
+        Before writing, run the self-check pass per
+        `AX_ARTIFACT_STYLE_SELF_CHECK`. In `refine` mode update sections in place per
+        `AX_LIVING_SPEC`. In `pivot` mode also
+        `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/pivot-formats.xml")`
+        (`AX_PIVOT_REQUIRES_SUPERSESSION`); in `rewrite` mode write fresh — no supersession. For a brand-new scope, append the `🚧 (awaiting root sync)` placeholder row to the portal Scopes table per `AX_PORTAL_READ_ONLY_WITH_PLACEHOLDER_EXCEPTION` — every other portal edit belongs to the root flow. Write in review-state per `AX_SPEC_LIFECYCLE` — prepend a `CHANGE_MANIFEST` (`READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/formats/change-manifest.xml")`) and mark changed lines `✚`/`~` (greenfield → manifest only, no per-line marks); compress folds it to master downstream after the change ships. Then close with the integrity check per `AX_CLOSE_WITH_INTEGRITY_CHECK`: run `sdd-check --all specs/<scope>` (anchor balance + required sections + links) and resolve any finding. Then `READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/review-lifecycle.directive.xml")` — internal critic → publish (MR) → external review → compress + merge on approval. After the spec merges to master, handoff is to scaffold (interface scopes have no modules).
+        Approval Check. STOP.
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <ChatOutput>
+    Service line — dim, internal, never narrated (per `AX_NO_PROCESS_NARRATION`):
+    `📐 CON_R<N> · <scope> · <mode> · conf=<LOW|MEDIUM|HIGH>`. Breadcrumb milestones (per
+    `BREADCRUMB_FORMAT`): Interface · Versioning · Compatibility · Spec.
+
+    <Contract id="MESSAGE_LAYOUT">
+      A step-boundary / decision message (the decision card) is sectioned with markdown headers, in
+      this order. Skip any section empty for this step. During free dialogue inside a step the agent
+      does NOT print this layout — it just talks.
+
+      `<dim service line>`        — internal anchor + scope + mode + confidence (supplied by the branch)
+      `<breadcrumb>`              — per `BREADCRUMB_FORMAT`
+
+      ## `<glyph>` `<scope>` — одной фразой, что делаем
+
+      ### 🤔 Как я понял задачу    — per `UNDERSTANDING_BLOCK_FORMAT` (goes at the TOP)
+      ### главное решение          — the crux in plain words; add a diagram per `FLOW_DIAGRAM_WHEN` if it is a flow
+      ### ❓ Вопросы — реши N        — per `QUESTION_FORMAT`
+      ### ↓ Детали — по желанию    — reasoning, full comparison, change-list (per `AX_PROGRESSIVE_DISCLOSURE`)
+    </Contract>
+
+    <Contract id="BREADCRUMB_FORMAT">
+      One line under the service line: this session's milestones, each with a status marker — `✅` done
+      · `▶️` now · `░` not yet. Delta only; never re-list everything already settled. This is the
+      «where are we», and it replaces a verbose run-on of finished steps.
+
+      `<Веха>` ✅ · `<Веха>` ✅ · `<Веха>` ▶️ · `<Веха>` ░ · `<Веха>` ░
+    </Contract>
+
+    <Contract id="UNDERSTANDING_BLOCK_FORMAT">
+      The agent's compressed read of the task — its own confirmation of blind spots so the operator can
+      catch a misread. A `### 🤔 Как я понял задачу` section near the TOP, then an italic blockquote,
+      explicitly optional, 2–3 sentences: the essence + the single riskiest assumption, with the
+      assumption linked to the question it maps to. Never a restate of settled content.
+
+      ### 🤔 Как я понял задачу
+      > _Можно не читать, если доверяешь._
+      > квинтэссенция — что считаю главным.
+      > **Где могу ошибаться:** самое хрупкое допущение — это вопрос Q`<N>`.
+    </Contract>
+
+    <Contract id="SIDE_DIVE_FORMAT">
+      A sub-topic dive inside a step collapses to two lines, not a five-field Return Summary:
+
+      → ушли в `<тема>`
+      ← `<итог одной фразой>`
+    </Contract>
+
+    <Contract id="FLOW_DIAGRAM_WHEN">
+      When a decision is about a flow — data moving, state transitions, start / stop conditions — draw
+      a tiny ASCII diagram; one glance beats a paragraph. This is the one place a fenced block is
+      allowed inside an operator message (alignment matters). Keep it small.
+
+      ```
+      [сеть] [auth] [конфиг]  ──всё есть──►  ОПРОС идёт
+              ▲                                  │
+              └──── снова есть ──── ПАУЗА ◄───────┘  что-то пропало
+      ```
+    </Contract>
+
+    <Axiom id="AX_PROGRESSIVE_DISCLOSURE" cross-cutting="true">
+      Decision first, reasoning on demand. The must-read top of a message is short: where we are + my
+      read + what to decide. Everything heavy — full option comparison, evidence, the change-list,
+      derivations — goes BELOW a `### ↓ Детали — по желанию` header. Never dump reasoning above the
+      questions. Facts already verified collapse to one line («сверился: …»); uncertainties that need
+      the operator BECOME the questions — never list them twice.
+    </Axiom>
+  </ChatOutput>
+
+  <ArtifactOutput>
+    <!-- spec-structure + pivot formats load lazily at STEP_6 (used only when writing) — see ExecutionPlan. -->
+    <Contract id="DECISION_LOG_ENTRY_FORMAT">
+      ```markdown
+      ### D-NNN — <short title>
+      - **Status:** active | superseded | rejected | deferred
+      - **Recorded:** session <DirectiveName>, <scope-name>
+      - **Why:** <operator's own wording>
+      - **Risk accepted:** <if any>
+      - **Rejected alternatives:** <list with brief reasons>
+      - **Supersedes:** D-NNN (when superseding a prior decision)
+      ```
+    </Contract>
+  </ArtifactOutput>
+</SddInterface>

package/dist/ai/directives/sdd-v2/interview-protocol.directive.xml

@@ -0,0 +1,284 @@
+<SddInterviewProtocol keywords="interview, coverage-map, triage, amplification, rounds, defaults-first, weak-spots, closure, stakes-split, one-question-per-message, ask-tool-binding, sdd-interview-protocol" type="directive" ver="2.1">
+  <Mission>
+    Run ONE operator interview for an authoring step. Loaded lazily by a branch step (scope
+    STEP_2 / STEP_3, infra STEP_2, interface STEP_2, module STEP_2) via `READ_AND_USE_DIRECTIVE`; the calling
+    step supplies the scope-type + its focus and stays the owner of what gets written. Inherits
+    the router core (language, dialogue, safeguard, diverge, no-narration) — not repeated here.
+
+    This protocol equips the interview declared by `AX_OPERATOR_SAFEGUARD` with instruments: a
+    live coverage map, an amplification triage, defaults-first rounds, and a map-based closure
+    criterion. The safeguard axiom stays the source of the interviewing instinct; this directive
+    only gives it structure.
+
+    Input — scope-type, calling-step focus, intake gathered so far. Output — a closed coverage
+    map + the captured answers and decisions, returned to the calling step. This directive writes
+    no artifact; control returns to the caller at CLOSE.
+
+    **Single-fork fast path.** When the caller hands the protocol exactly one named fork (not a
+    whole authoring step), skip `STEP_1_INIT_MAP` and `STEP_2_TRIAGE`; enter `STEP_3_ROUNDS` with a
+    one-item map (the fork), close it per `AX_STAKES_SPLIT` / `AX_ASK_TOOL_BINDING`, return.
+  </Mission>
+
+  <BeliefState deps="AX_OPERATOR_LANGUAGE, AX_OPERATOR_SAFEGUARD, AX_DIALOGUE_DISCIPLINE, AX_DIVERGE_BEFORE_RECOMMEND, AX_NO_PROCESS_NARRATION">
+    <Axiom id="AX_COVERAGE_MAP_CLOSURE">
+      The interview ends when the coverage map is closed — every topic `[✔]` or explicitly skipped
+      with a recorded reason — never when a question count is reached, and never by a silent Approval
+      Check. After every operator answer, re-check the map: an answer that opens a new hole or risk
+      adds a topic or reopens a closed one (thread-pulling per `AX_OPERATOR_SAFEGUARD` — that axiom
+      owns the instinct; this one binds it to the map). A skip on a high-stakes topic goes through
+      `H_HIGH_STAKES_SKIP`.
+    </Axiom>
+
+    <Axiom id="AX_DEFAULTS_FIRST">
+      Where a defensible default exists, lead with it: propose one concrete option drawn from real
+      production practice and ask the operator to confirm or correct — instead of an open question.
+      The default MUST be the result of `AX_DIVERGE_BEFORE_RECOMMEND`, not the first typical answer.
+      Reserve open questions for decisions that are genuinely operator-owned (business goals, risk
+      acceptance, priorities) or where no defensible default exists; open-ended deepening on any
+      topic happens when the operator asks for it.
+    </Axiom>
+
+    <Axiom id="AX_AMPLIFICATION_OPT_IN">
+      Amplifications are opt-in: after triage the agent PROPOSES a set from the catalog, the operator
+      confirms; the default for small tasks is «none active». State an empty proposal explicitly —
+      «усиления не нужны, потому что …» — it is a valid triage outcome, not a silent omission. A
+      confirmed amplification becomes a map topic and its directive loads lazily via
+      `READ_AND_USE_DIRECTIVE` at the moment its topic opens, never up front.
+    </Axiom>
+
+    <Axiom id="AX_STAKES_SPLIT">
+      The stakes of a question decide its delivery form — this overrides any round-grouping default:
+      - A **развилка** (architecture, a trust boundary, an irreversible or hard-to-undo choice) → ONE
+        question per message, full form per `QUESTION_MESSAGE_FORMAT`, answered via `AskUserQuestion`
+        before the next question is composed.
+      - A **default confirmation** (naming, a low-risk default, an obvious yes/no) → batched, up to 4
+        per `AskUserQuestion` call, per `BATCH_CONFIRM_FORMAT`.
+      Unsure which it is → treat as развилка. Burying a genuine fork inside a batch is the exact
+      failure this axiom exists to prevent.
+    </Axiom>
+
+    <Axiom id="AX_ONE_QUESTION_SEQUENTIAL">
+      Развилки go strictly one at a time: compose question N+1 only after the answer to question N is
+      in. Each next question MUST account for every prior answer in the interview — a question whose
+      premise an earlier answer already invalidated is a protocol defect, not a style issue. The
+      counter in `## Вопрос <X> из <Y>` is owned here: X is this question's ordinal in the interview;
+      Y is questions already asked plus развилки still open on the coverage map. When thread-pulling
+      opens a new topic, Y grows and the growth shows in the next map line — never silently.
+    </Axiom>
+
+    <Axiom id="AX_ASK_TOOL_BINDING">
+      Every развилка ends in one `AskUserQuestion` call, bound to its chat message:
+      - The chat message carries the full material (`QUESTION_MESSAGE_FORMAT`); the ASK call carries
+        only short option labels + one-line descriptions — never move the argument itself into the ASK.
+      - Options appear in the ASK in the SAME order they were printed in the message.
+      - A recommendation prints first in the message too (letter A) and carries «(рекомендую)» in its
+        ASK label — printed order and recommended-first then agree.
+      - «Other» is supplied by the tool automatically; never add a manual equivalent.
+      - Tool unavailable → drop only the ASK call; the развилка message still follows
+        `QUESTION_MESSAGE_FORMAT` and the answer arrives as free text, otherwise falling back to the
+        caller's plain-text `QUESTION_FORMAT` when one applies. Batched default confirmations use one
+        ASK call covering 2–4 questions.
+    </Axiom>
+
+    <Axiom id="AX_VISUAL_WHEN_RELATIONAL">
+      When a question's subject is relational — a flow, a boundary, a structure, a lifecycle, or
+      variants that differ in shape — draw a compact ASCII picture BEFORE the variants, per
+      `formats/diagram-vocabulary.xml` (`AX_DIAGRAM_DISCIPLINE`: ≤7 nodes, one diagram per idea). A
+      question about a single scalar choice stays prose; a diagram of one node is noise, not clarity.
+      The same relation later lands in the spec as mermaid — the module/scope Overview if it is the
+      floor diagram (`AX_OVERVIEW_DIAGRAM_FLOOR`), else inline where the section needs it. The chat
+      ASCII is the operator's preview of the shape they are approving.
+    </Axiom>
+
+    <Axiom id="AX_SCANNABLE_TEXT">
+      The operator surfs a question message, they do not wade through it: bold marks the load-bearing
+      word inside a bullet, not the whole sentence; each block opens with its own emoji anchor;
+      paragraphs stay ≤3 lines; no monolithic prose wall. Emotion is seasoning, not paint — anchors and
+      an occasional marker, never an emoji on every line.
+    </Axiom>
+  </BeliefState>
+
+  <TopicCatalog>
+    Base topics — every interview starts with these (map labels in Russian):
+
+    | Topic | Substance |
+    |---|---|
+    | Цель и не-цель | what this scope delivers; what it explicitly refuses to do in this iteration |
+    | Потребители | who consumes the result and what they expect from it |
+    | Слабые места | MANDATORY: holes, contradictions, unstated expectations of the intake — name them to the operator, per `AX_OPERATOR_SAFEGUARD` |
+    | Внешние зависимости | what outside this scope must exist / hold for the design to stand |
+
+    scope-type block — append per the caller's scope-type:
+
+    | scope-type | Topics |
+    |---|---|
+    | product | Пользователи (who exactly, how many) · Метрика успеха/провала (both, not only success) · Зачем сейчас (why this, why now) · Worst case (the worst plausible scenario and who pays for it) |
+    | library | Разработчики-потребители (which teams / repos) · DX (how consumption should feel; feeds Golden DX) · Версии (versioning + compatibility promises) |
+    | infrastructure | Окружения (dev / CI / prod parity) · Доставка (how changes reach consumers) |
+    | interface | Стороны контракта (producers and consumers, who owns the schema) · Эволюция (how the contract changes without breaking consumers) |
+
+    The calling step MAY narrow or extend the block for its focus (e.g. scope STEP_3 keeps only
+    what the Requirements Gate still misses); «Слабые места» stays on every map.
+  </TopicCatalog>
+
+  <AmplificationCatalog>
+    Deep-dive modules; each is a separate directive authored elsewhere and loaded lazily
+    (`AX_AMPLIFICATION_OPT_IN`):
+
+    | Amplification | Directive | Triage trigger |
+    |---|---|---|
+    | security | `ai/directives/sdd-v2/amplify-security.directive.xml` | external users, or data crossing a trust boundary |
+    | nfr | `ai/directives/sdd-v2/amplify-nfr.directive.xml` | load / latency / volume significant enough to shape the design |
+    | storage | `ai/directives/sdd-v2/amplify-storage.directive.xml` | state persisted beyond a single run |
+    | observability | `ai/directives/sdd-v2/amplify-observability.directive.xml` | someone must diagnose this in production |
+  </AmplificationCatalog>
+
+  <HaltConditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | `H_HIGH_STAKES_SKIP` | Operator insists on skipping an unclosed high-stakes topic — name the concrete cost (per `AX_OPERATOR_SAFEGUARD`); on a confirmed skip record `[✗ skip: <причина>]` in the map and proceed |
+  </HaltConditions>
+
+  <ExecutionPlan>
+    <Step id="STEP_1_INIT_MAP">
+      <Goal>Build and show the coverage map.</Goal>
+      <Action>
+        Assemble the map: base topics + the scope-type block from `TopicCatalog`, narrowed /
+        extended by the calling step's focus. Mark topics the intake already answers `[✔]` — ask
+        only what a decision still needs. Render per `COVERAGE_MAP_FORMAT` with a one-line plan
+        («что осталось закрыть»); proceed straight to triage.
+      </Action>
+    </Step>
+    <Step id="STEP_2_TRIAGE">
+      <Goal>Decide which amplifications this task deserves.</Goal>
+      <Action>
+        One compact block of 3–5 closed questions (yes / no / short pick), mandatory even when the
+        task looks small: external users or external data? load significant? state persisted?
+        must this be diagnosable in production? — plus at most one triage question specific to the
+        intake. From the answers, propose an amplification set per `AmplificationCatalog` with the
+        small-task default «none active» (`AX_AMPLIFICATION_OPT_IN`); operator confirms. Confirmed
+        amplifications become map topics on the «Усиления» line. STOP.
+      </Action>
+    </Step>
+    <Step id="STEP_3_ROUNDS">
+      <Goal>Close the map, one topic at a time, in the shape its stakes demand.</Goal>
+      <Action>
+        Loop until the map is closed (`AX_COVERAGE_MAP_CLOSURE`); each round:
+        1. Show the map per `COVERAGE_MAP_FORMAT`, pick the next open topic, mark it `[▶]`.
+        2. Split by stakes (`AX_STAKES_SPLIT`): a развилка → one message per
+           `QUESTION_MESSAGE_FORMAT`, answered before the next question is composed
+           (`AX_ONE_QUESTION_SEQUENTIAL`); a default confirmation → collect it and batch up to 4
+           per `BATCH_CONFIRM_FORMAT`.
+        3. Shape each question per `AX_DEFAULTS_FIRST` — a concrete default to confirm or correct —
+           and bind its chat message to the `AskUserQuestion` call per `AX_ASK_TOOL_BINDING`.
+        4. After each answer, update the map and pull the thread per `AX_COVERAGE_MAP_CLOSURE`
+           (new hole → new / reopened topic; a развилка whose premise the answer invalidated is
+           recomposed, not asked as planned — `AX_ONE_QUESTION_SEQUENTIAL`).
+        5. An amplification topic opens → `READ_AND_USE_DIRECTIVE` its directive from
+           `AmplificationCatalog` and run its questions as this round, split by stakes the same way.
+        A skip request on a high-stakes topic → `H_HIGH_STAKES_SKIP`.
+      </Action>
+    </Step>
+    <Step id="STEP_4_CLOSE">
+      <Goal>Verify closure and return to the caller.</Goal>
+      <Action>
+        Gate per `AX_COVERAGE_MAP_CLOSURE`: every topic `[✔]` or `[✗ skip: <причина>]` — an open
+        or `[▶]` topic sends the flow back to STEP_3. Show the final map + a compact digest of
+        answers and decisions (Russian), including skips with reasons. Hand the digest to the
+        calling step — it owns the Approval Check, artifact writing, and any Decision Log entries.
+      </Action>
+    </Step>
+  </ExecutionPlan>
+
+  <ChatOutput>
+    The map per `COVERAGE_MAP_FORMAT` opens every round — it is the operator's progress view, so
+    keep it current and compact (per `AX_NO_PROCESS_NARRATION`, the map replaces narration about
+    what the interview is doing).
+
+    <Contract id="COVERAGE_MAP_FORMAT">
+      Live coverage map, shown to the operator compactly before every round. Topic labels in Russian;
+      ≤ 72 columns; statuses: `[✔]` closed · `[▶]` in progress · `[ ]` open · `[✗ skip: <причина>]`.
+
+      Покрытие: Цель/не-цель [✔] · Потребители [▶] · Слабые места [ ] · Зависимости [ ]
+      Усиления:  security [▶] · storage [✗ skip: прототип, данных нет]
+
+      4–6 topics per line; the «Усиления» line appears only when at least one amplification is
+      active or skipped. The map is session state for the dialogue — the calling step decides what
+      from the answers lands in the artifact; the map itself stays out of the spec.
+    </Contract>
+
+    <Contract id="QUESTION_MESSAGE_FORMAT">
+      The развилка message — one question, full context, live markdown (never fenced). Blocks in
+      order; skip a block only when genuinely empty:
+
+      1. Coverage map line (`COVERAGE_MAP_FORMAT`).
+      2. `## Вопрос <X> из <Y> · <topic, no question mark>` — X/Y per `AX_ONE_QUESTION_SEQUENTIAL`.
+      3. `**Решаем одной строкой:** <the fork, one sentence>`.
+      4. An ASCII diagram — only when the subject is relational (`AX_VISUAL_WHEN_RELATIONAL`).
+      5. `**📌 Что известно**` — 2–5 bullets, load-bearing words bold, specific to THIS question —
+         not a restate of the session (`AX_SCANNABLE_TEXT`).
+      6. `**⚖️ Варианты**` — each variant: `**<Letter>. <name>**` then `✅ <pros, · -separated>` /
+         `⚠️ <cons, · -separated>`. 3+ variants with comparable criteria → a criteria×variant table
+         INSTEAD of the lists (rows = criteria, columns = variants; the killer cell bold).
+      7. `**🎯 Куда клонюсь:** <letter> — <why, one sentence>` — omit on high-stakes questions where
+         pre-anchoring is wrong (`AX_DEFAULTS_FIRST`).
+      8. The `AskUserQuestion` call (`AX_ASK_TOOL_BINDING`) — options in printed order.
+
+      <Example>
+        Покрытие: Цель/не-цель [✔] · Потребители [✔] · **формат спеки [▶]** · Зависимости [ ] · Слабые места [ ]
+
+        ## Вопрос 3 из 6 · Куда переезжает разросшаяся ячейка Entity Inventory
+
+        **Решаем одной строкой:** ячейка таблицы с абзацем на восемь предложений не читается во
+        вьювере — куда девать текст при миграции на v2-формат.
+
+        ```
+        [ячейка: 8 предложений] ──migrate──► ??? ──рендер во вьювере──► [читаемая таблица]
+                                              │
+                                     куда: подсекция? свернуть? урезать?
+        ```
+
+        **📌 Что известно**
+        - Правило F2 запрещает **абзацы и списки внутри ячейки** — только одна короткая строка.
+        - Развёрнутый текст должен **переехать в подсекцию под таблицей**, а не исчезнуть.
+        - `sdd-check` уже умеет **считать длину ячейки** — порог просто пока не задан.
+
+        **⚖️ Варианты**
+
+        **A. Короткая ячейка + подсекция `### <ID> — детали`**
+        ✅ таблица остаётся индексом · ничего не теряется · механически проверяемо
+        ⚠️ спека становится длиннее на число подсекций
+
+        **B. Урезать ячейку до одной фразы, остальное — в Decision Log**
+        ✅ таблица короче любой подсекции
+        ⚠️ решение теряет прямую связь со строкой таблицы — придётся искать отдельно
+
+        **🎯 Куда клонюсь:** A — подсекция держит связь «строка → детали», ничего не отрывается от
+        таблицы.
+
+        (AskUserQuestion: «A. Подсекция под таблицей (рекомендую)» · «B. В Decision Log»)
+      </Example>
+    </Contract>
+
+    <Contract id="BATCH_CONFIRM_FORMAT">
+      Default confirmations — one compact block, then ONE `AskUserQuestion` call with 2–4 questions.
+      Per item: one bold line (the default) + one plain line (the alternative and when it wins). No
+      «Что известно» blocks, no diagrams. An item that provokes discussion is promoted to a развилка
+      in the next message, not resolved inside the batch.
+    </Contract>
+
+    <Contract id="NEXT_STEP_MENU_FORMAT">
+      Rendered by the CALLING step's final step, after its artifact is written and verified. Shape:
+
+      1. One ✅ line — what was produced and what was checked
+         (`✅ Спека <path> записана · язык проверен · <N> диаграмм`).
+      2. `**Что дальше?**` + one `AskUserQuestion` call. Options (2–4) come from the caller's own
+         candidate table; the recommended option first with «(рекомендую)»; CHAINED options are
+         first-class («декомпозиция + критик следом», «scaffold + сразу execute») — one pick launches
+         the whole chain, the agent runs it without stopping between links unless a link fails.
+         Always include «Закончить сессию» last.
+      3. On pick: invoke the corresponding skill(s) / directive flow(s) directly — never answer with
+         «запусти /sdd-X сам».
+    </Contract>
+  </ChatOutput>
+</SddInterviewProtocol>