NODEDC_1C/.codex/skills/domain-case-loop/references/scenario_tree_acceptance_canon.md

Scenario-tree acceptance canon

Core idea

For follow-up-heavy business domains, the unit of acceptance is not a flat list of isolated questions.

The unit of acceptance is a scenario tree:

• a root business question;
• one or more critical child drilldowns;
• explicit transitions between steps;
• explicit semantic carryover between steps.

If the root works but a critical child transition breaks, the domain is not hardened.

Model the domain as a tree

For each scenario, define:

• root node
• critical child nodes
• critical edges
• primary user path

Example for inventory:

• root: stock snapshot on date
• child: selected item -> supplier provenance
• child: selected item -> purchase documents
• child: selected item -> aging on the same date
• child: selected item -> sale trace

The primary user path is the path a real user is most likely to take first, not the prettiest canonical wording.

Node acceptance

A node is considered covered only if all of these are true:

• the business meaning is understood correctly;
• the expected intent / capability is selected;
• the answer shape matches the requested business object;
• the answer begins with a direct user-facing answer when such an answer is expected;
• the answer is evidence-backed rather than heuristic-masked.

Examples:

• asking for supplier provenance must answer with the supplier first, not only with raw documents;
• asking for old stock must answer with item-level old-stock positions, not with a raw document dump;
• asking for residues/items/contracts must not silently downgrade to lower-level movements.

Edge acceptance

Each critical edge must define its required carryover invariants.

Typical invariants:

• selected object survives from previous assistant output
• originating date / period survives into follow-up filters
• warehouse survives if the follow-up still targets the same stock slice
• organization survives if the previous slice was organization-bound
• route family remains in the same business contour unless the user clearly changed intent

If an edge loses a required invariant, that is a real regression even if the target node works in isolation.

Mandatory paraphrase families

Every critical node or edge must be validated in a small paraphrase family instead of one curated wording only.

Minimum family:

• canonical
• colloquial
• ui_selected_object

Examples:

• canonical: От какого поставщика куплен товар X
• colloquial: Кто поставил этот товар
• ui_selected_object: По выбранному объекту "X": кто это поставил нам

If canonical works but colloquial or UI-generated follow-up fails, the node/edge is not accepted.

Acceptance matrix

The analyst must produce or update a scenario_acceptance_matrix.md artifact for every multi-step scenario or pack.

Minimum matrix columns:

• scenario id
• node id or edge id
• user path role (root, critical_child, supporting)
• wording family (canonical, colloquial, ui_selected_object)
• expected business meaning
• expected intent
• expected capability / recipe
• required carryover invariants
• expected answer shape
• actual outcome
• status (pass, partial, fail)
• defect class

Defect classes

Use these classes explicitly:

• semantic_understanding_gap
• edge_carryover_gap
• answer_shape_mismatch
• ordering_semantics_mismatch
• runtime_capability_gap
• loop_coverage_gap

Definitions:

• semantic_understanding_gap: the system did not understand the real user meaning
• edge_carryover_gap: the follow-up lost date / object / scope across steps
• answer_shape_mismatch: the business object in the answer does not match the requested object
• ordering_semantics_mismatch: ranking / chronology semantics are wrong
• runtime_capability_gap: the product contour truly lacks the route / intent / capability / extractor / recipe
• loop_coverage_gap: the runtime could support the path or nearly support it, but the analyst/orchestrator never treated that path as mandatory acceptance coverage

Analyst responsibilities

The analyst must:

• review the scenario tree, not just individual turns;
• compare expected and actual user path transitions;
• call out broken edges explicitly;
• verify colloquial and UI-generated variants as first-class coverage;
• verify direct-answer-first behavior where the user asked a direct lookup question;
• verify answer granularity and ordering semantics;
• lower the score when any critical edge or paraphrase family is broken.

Orchestrator responsibilities

The orchestrator must:

• define the tree before iterating deeply;
• prioritize the primary user path first;
• rerun at least one colloquial variant and one UI-selected-object variant for each critical branch;
• treat a broken critical edge as an unfinished scenario even if the root node works;
• route coder work to the narrowest broken edge or node rather than issuing broad “improve the domain” tasks.

Stop and acceptance rules

Do not accept a domain when:

• only the root node works;
• only one curated phrasing works;
• selected-object follow-up is broken;
• на эту дату / на ту дату loses the originating date;
• the answer shape is wrong for the business question;
• chronology / ranking semantics are inverted.

Accepted requires:

• score >= 80
• no unresolved P0
• critical path edges pass
• canonical + colloquial + UI-selected-object variants pass for critical branches
• no silent heuristic masking