gennady 0.8.3 → 0.8.4-draft.2

package/ai/directives/sdd/discovery.directive.xml

@@ -1,824 +0,0 @@
-<SddDiscovery keywords="discovery, scope, vision, golden-dx, design-variants, decision-log, scope-rules, scope-type, infrastructure, contracts, library, product, living-spec, frame-stack, evidence-hygiene, runtime-backing, sdd-scope-discovery" type="directive" ver="3.1">
-  <Directive_Context>
-    <Mission>
-      Turn the operator's intent for a scope into an approved scope spec at `specs/<scope-name>/<scope-name>.spec.md`.
-
-      Input: scope name + scope-type + operator intent (raw idea, or existing spec for `refine` / `pivot`).
-      Output: self-contained living scope spec. The required section set depends on `scope-type`:
-      - `infrastructure` → Vision, Tool Stack (Decision Log per tool), Dev Workflow Example, File Structure, Effective Rules, Handoff.
-      - `contracts` → Vision, Versioning Policy, Interfaces (schema / OpenAPI / proto), Compatibility Matrix, Decision Log, Handoff.
-      - `library` → Vision, Golden DX, Public API Surface, DbC contracts, Architecture, Decision Log, Handoff.
-      - `product` → Vision, Project Type, Golden DX, Requirements Gate, Architecture variants, Decision Log, Handoff to `module-decomposition`.
-
-      Living spec: no frozen sections. Any section may be updated via `refine` without a full pivot ritual. `pivot` remains reserved for breaking / incompatible changes.
-
-      Out of scope: module decomposition, entity inventory, DbC — those belong to `module-decomposition` for library / product scopes.
-
-      **Glossary.** Scope = architecturally cohesive unit (own runtime / stack / deployment target / UX surface). scope-type ∈ {infrastructure, contracts, library, product}.
-    </Mission>
-  </Directive_Context>
-
-  <Belief_State>
-    <Axiom id="AX_DIRECTIVE_MODE">
-      **Three modes, auto-detected:**
-      - `greenfield` — scope spec does not exist.
-      - `refine` — extension or tightening of an existing spec (new requirements, new tools, new contracts) without replacing architecture.
-      - `pivot` — replacement of foundational decisions (architecture swap, scope-type swap, tool stack swap). Triggers supersession in the Decision Log.
-
-      Discriminator: if the old decision remains valid in parallel with the new one → `refine`. If the old decision is replaced by an incompatible one → `pivot`.
-    </Axiom>
-
-    <Axiom id="AX_SCOPE_TYPE_BRANCH">
-      scope-type drives the flow of the directive:
-
-      | scope-type | STEP_3 | STEP_4 | STEP_5 | STEP_6 |
-      |---|---|---|---|---|
-      | infrastructure | Tool Categories + Choices | Dev Workflow Example | File Structure | Effective Rules |
-      | contracts | Interface Declaration | Versioning Policy | Compatibility Matrix | — |
-      | library | Requirements Gate | Golden DX | Architecture | — |
-      | product | Requirements Gate | Golden DX | Design Variants | Architecture Choice |
-
-      STEP_2 (Intent Capture), STEP_7 (External Dependencies Audit), and STEP_8 (Final Spec) are identical across all types.
-    </Axiom>
-
-    <Axiom id="AX_MODE_AUTO_DETECT_OR_HALT">
-      | spec exists? | verb | Mode |
-      |---|---|---|
-      | No | — | greenfield |
-      | Yes | refine / extend / add / расширь / добавь / уточни | refine |
-      | Yes | pivot / replace / заменим / поменяем архитектуру | pivot |
-      | Yes | none of the above | HALT `H_AMBIGUOUS_MODE` — ask binary: refine or pivot? |
-    </Axiom>
-
-    <Axiom id="AX_PORTAL_READ_ONLY_WITH_PLACEHOLDER_EXCEPTION">
-      `discovery` reads `specs/README.md` for project context (vision, scope graph, sibling scopes). It MUST NOT rewrite the file. The narrow exception (per `setup` `AX_PORTAL_PRIMARY_OWNER`): when `discovery` creates a brand-new scope, it MAY append one placeholder row to the Scopes table tagged `🚧 (awaiting setup sync)`. Any other edit is forbidden — promote `setup` 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_IS_SOLE_SOURCE">
-      The directive reads specs and never reads code. The only directive permitted to read code is `audit`.
-      - `greenfield` — operator input + rule files only.
-      - `refine` / `pivot` — Portal (for context) + existing scope spec.
-    </Axiom>
-
-    <Axiom id="AX_INFRASTRUCTURE_FLOW">
-      For scope-type=infrastructure:
-
-      **Tool categories — two classes.** Mandatory: vcs, package-management, git-hooks. Optional: type-check, linting, formatting, test-unit, test-e2e, test-ui, bundler, ci, monorepo-tool, docs. The agent proposes a subset from intent. Mandatory categories cannot be dropped.
-
-      **vcs is always mandatory.** Resolves to `ai/directives/infra/git-setup.xml`.
-
-      **Per tool category: 2–3 candidates with trade-offs.** Operator picks → Mandatory Rationale Pull → Decision Log entry. No tool may be locked without a Decision Log entry.
-
-      **Tool interaction check.** After every tool is chosen, verify compatibility (linter vs formatter, test runner vs type-check, CI vs package manager).
-
-      **Effective rules derived from tools.** After tool stack is finalized, look up each chosen tool in `ai/directives/knowledge.xml` `<Rules>` section: find every rule whose `<Triggers>` match the tool name or its config artefacts. Record matched rule `<File>` paths in spec section 5 Effective Rules. Missing-rule handling: governed by `AX_SCOPE_RULES_DECLARATION` (in-session operator pick — skip / research-and-author / defer).
-
-      **Dev workflow example is required.** The spec includes a Developer Workflow Example (shell-script shape) before final approval.
-    </Axiom>
-
-    <Axiom id="AX_PRODUCT_LIBRARY_FLOW">
-      For scope-type=product and scope-type=library:
-
-      **Requirements gate before design.** Architecture variants are forbidden until REQUIREMENTS_GATE is closed. Required: Functional Requirements, Non-Functional Constraints, Out-of-Scope, Project-Wide Rules (Rules).
-
-      **Golden DX example gate.** A Golden DX Example is mandatory before Design Variants. library → Public API DX. product → UX-flow DX or CLI DX depending on Project Type.
-
-      **Project Type scales depth** (product only):
-      - `app` (mobile / desktop / spa): 2–3 architectural variants.
-      - `service-module-sdk`: 2–3 variants across transport + persistence.
-      - `cli-utility`: 1–2 variants (minimal depth).
-
-      **YAGNI guard.** Only abstractions needed for v1. Future-proof extensions without a confirmed consumer are forbidden.
-    </Axiom>
-
-    <Axiom id="AX_CONTRACTS_FLOW">
-      For scope-type=contracts:
-      - 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 contracts scope.
-    </Axiom>
-
-    <Axiom id="AX_RUNTIME_BACKING_EXPLICIT">
-      For product / library scope specs, runtime backing posture is declared at the scope level inside Requirements & Constraints under «Runtime Backing & Deferred Scope»:
-      - Posture per major capability: `not-implemented` | `simulation` | `real-runtime`.
-      - Deferred scope: parts whose real runtime is intentionally not delivered in v1, with reason.
-      - Trust boundaries that require a real runtime hook (auth, payments, persistence) are listed explicitly.
-
-      Establishing posture early prevents `module-decomposition` and `task-scaffolding` from misclassifying simulation seams as real implementations.
-    </Axiom>
-
-    <Axiom id="AX_SCOPE_RULES_DECLARATION">
-      Scope-wide rules are declared in spec Rules. Categories with directory mapping:
-      - coding → `ai/directives/coding/<rule>.xml`
-      - testing → `ai/directives/testing/<rule>.xml`
-      - architecture → `ai/directives/architecture/<rule>.xml`
-      - infra → `ai/directives/infra/<rule>.xml`
-
-      Every rule reference must resolve to an existing file. Missing → operator picks resolution IN-SESSION (never a halt, never an autonomous task):
-      - **skip** — tool's own defaults are the discipline; record in Decision Log.
-      - **research-and-author** — agent WebFetches authoritative docs (official source from `package.json#homepage` or operator-supplied URL), drafts rule file, operator approves before write to `ai/directives/<category>/<name>.xml`. Drafts capture TIMELESS engineering practice only — discipline, trade-offs, anti-pattern categories, binary invariants. NOT captured: version numbers, CLI flags, config-syntax snippets, plugin lists (those churn between releases; they live in `package.json` / config files).
-      - **defer** — record as Open Risk in Handoff with `Owner: operator-action`; proceed.
-
-      Operator refuses to choose → `H_MISSING_RULE_FILE`. Otherwise no halt.
-    </Axiom>
-
-    <Axiom id="AX_RULE_ACTIVATION">
-      Two stages:
-      - Stage A — relevance per category (recommend activate / recommend skip + rationale). Operator locks the list.
-      - Stage B — per-rule axiom walkthrough (infra/* and architecture/* rules only). Read `Mission` + `Belief_State` + `Reward_Criteria`. Operator decides Accept / Adapt / Override → Decision Log.
-
-      Defaults: infra/*, architecture/* → walk through now. coding/*, testing/* → deferred — phase-subagent loads them at phase entry per `phase-execution-protocol`.
-    </Axiom>
-
-    <Axiom id="AX_DECISION_LOG_REQUIRED">
-      Every non-trivial decision → Decision Log entry. Format: D-NNN, Status, Recorded, Why (operator's wording), Risk accepted, Rejected alternatives. IDs are stable.
-    </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 (Pivot Invalidation List) enumerates downstream artifacts requiring `refine-module` / reopen — consumed by `audit` via `AX_STALE_AFTER_PIVOT_VERIFICATION`.
-    </Axiom>
-
-    <Axiom id="AX_HANDOFF_TO_MODULE_DECOMPOSITION">
-      For product / library scope: the spec carries Handoff with primary input for `module-decomposition`, named abstractions, open risks.
-    </Axiom>
-
-    <Axiom id="AX_CROSS_SCOPE_DEPENDENCIES">
-      Scope spec declares `depends-on` edges in Scope Dependencies. These edges feed cascade computation in `task-scaffolding`. Cross-scope contracts are sourced from `contracts`-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 (Portal, sibling specs, rule files).
-      - **Assumptions** — working assumptions awaiting confirmation; mark explicitly.
-      - **Hypotheses** — conjectures requiring operator validation before they harden into requirements.
-
-      Conflating the three is the most common path to false confidence; surface them in distinct lists.
-    </Axiom>
-
-    <Axiom id="AX_UNCOMFORTABLE_QUESTIONS">
-      Every meaningful frame includes ≥1 uncomfortable question — the kind that exposes hidden assumptions, degradation paths, or trust boundaries. Canonical seeds:
-      - What is the canonical source of truth for this entity / capability?
-      - What happens on dependency unavailability (graceful degradation vs hard failure)?
-      - Where does simulation end and real runtime begin?
-      - Who validates input at this trust boundary?
-      - Which assumption, if wrong, invalidates the design?
-
-      Skipping uncomfortable questions = false consensus.
-    </Axiom>
-
-    <Axiom id="AX_DX_FIRST">
-      For product / library scopes the Golden DX Example precedes Design Variants. DX shape:
-      - For library: the public-API DX (init / happy path / error path with commentary).
-      - For product app / spa / mobile / desktop: UX-flow DX.
-      - For product cli-utility: CLI DX (commands, flags, exit codes, sample sessions).
-      - For product service-module-sdk: API DX at the transport boundary.
-
-      DX is the empathic anchor for downstream design; without it Design Variants drift into solution-space gymnastics.
-
-      For product / library — this is the initial draft; ownership transfers post-first-`add-module` per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP` in module-decomposition.
-    </Axiom>
-
-    <Axiom id="AX_STACK_BASED_FLOW">
-      Discovery dialogue runs on an explicit frame stack. Main path: `INTAKE → SCOPE_TYPE_CONFIRM → INTENT_CAPTURE → TYPE_SPECIFIC_A → TYPE_SPECIFIC_B → TYPE_SPECIFIC_C → (TYPE_SPECIFIC_D) → FINAL_SPEC`. Disputes / dives / sub-topics open a nested frame; the stack is visible in TRACE_HEADER's `STACK` field. A sub-topic never silently stalls the parent frame.
-    </Axiom>
-
-    <Axiom id="AX_FRAME_EXIT_DISCIPLINE">
-      Every frame carries an exit condition. Status vocabulary: `OPEN` | `BLOCKED` | `READY_TO_RETURN` | `READY_TO_ADVANCE` | `DEFERRED`. Indefinite drilling without local resolution is forbidden. A sub-topic that does not block the current phase → status `DEFERRED`, return to parent with a Return Summary (per `RETURN_SUMMARY_FORMAT`).
-    </Axiom>
-
-    <Axiom id="AX_TRACE_ANCHORS">
-      Global: `DSC_R001`, `DSC_R002`, …. Frame: `F_INTENT_R01`, `F_REQ_R01`, `F_DV_R01`, etc. Stack rendered as `ROOT__<FRAME>__<SUBFRAME>` in the header.
-    </Axiom>
-
-    <Axiom id="AX_DIALOGUE_DISCIPLINE">
-      Phase agreement: agent signals `READY_TO_ADVANCE`; operator confirms. Neutral + critical: no auto-agree. Confidence explicit (`LOW` / `MEDIUM` / `HIGH`). No repeat questions. Context budget: compact on long dialogues.
-    </Axiom>
-
-    <Axiom id="AX_STATELESS_ARTIFACT">
-      The spec is self-contained. `module-decomposition` and `task-scaffolding` start without history of this conversation.
-    </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_OPERATOR_LANGUAGE">
-      **Directive prose (axioms, halt names, step procedures, contract identifiers, structural section headings) — English.**
-      **Operator-facing artifact prose and operator-facing messages — Russian.** Russian applies to:
-      - Spec body text (Vision sentence, Requirement statements, Decision Log `Why` / `Risk` content, Golden DX commentary).
-      - Halt messages emitted to the operator.
-      - Phase Progress free-text content.
-
-      English regardless of context: file paths, axiom IDs (`AX_*`), Trace anchors (`DSC_R<N>`), `F-NNN` / `D-NNN` / `H_*` IDs, status / scope-type tokens, BDD keywords, field labels (`**Status:**`, `**Why:**`).
-    </Axiom>
-  </Belief_State>
-
-  <Halt_Conditions>
-    | 🛑 ID | Trigger |
-    |---|---|
-    | `H_NO_INTAKE` | Empty intake |
-    | `H_AMBIGUOUS_MODE` | Spec exists + mode verb absent |
-    | `H_AMBIGUOUS_SCOPE_TYPE` | scope-type cannot be determined unambiguously |
-    | `H_LOW_CONFIDENCE` | Confidence `LOW` while locking architecture |
-    | `H_REQ_NOT_APPROVED` | Attempting Design Variants without a closed REQUIREMENTS_GATE (product / library) |
-    | `H_GOLDEN_NOT_APPROVED` | Attempting Design Variants without an approved Golden DX (product / library) |
-    | `H_MISSING_RULE_FILE` | Rule reference does not resolve to an existing file |
-    <!-- H_TOOL_RULE_MISSING removed — replaced by `AX_MISSING_RULE_RESEARCH_SUBFLOW` (interactive research+approval, never a halt) -->
-    | `H_PIVOT_NO_INVALIDATION_LIST` | `pivot` mode without Pivot Invalidation List |
-    | `H_BOOTSTRAP_REQUIREMENTS_MISSING` | STEP_7 finished without a Bootstrap Requirements section (even empty must be declared explicitly) |
-    | `H_OPERATOR_REJECT` | Operator rejected the spec |
-  </Halt_Conditions>
-
-  <Execution_Plan>
-    <Step id="STEP_0_INTAKE">
-      <Goal>Resolve scope name, scope-type, mode. Read Portal and rule registry for context.</Goal>
-      <Action>
-        1. Read `specs/README.md` if present (for project vision + graph context).
-        2. **Read `ai/directives/knowledge.xml` in full.** This is the canonical rule registry — it tells you what rule files exist, their `<Triggers>`, `<SkipWhen>`, `<ActivationHint>`, and `<RequiresVerification>`. You will use it throughout this session: to know which rules are available when selecting tools (infrastructure), to populate Project-Wide Rules (product/library), and to derive Effective Rules in the spec. Read it now — do not defer.
-        3. Resolve scope name from intake (or ask).
-        4. Stat `specs/<scope-name>/<scope-name>.spec.md`:
-           - Absent → `greenfield`.
-           - Present → apply `AX_MODE_AUTO_DETECT_OR_HALT`.
-        5. Resolve / confirm scope-type from intake or naming convention (`infra-*` → infrastructure hint).
-        6. Proceed to STEP_1.
-      </Action>
-    </Step>
-
-    <Step id="STEP_1_SCOPE_TYPE_CONFIRM">
-      <Goal>Lock scope-type and outline which sections the spec will carry.</Goal>
-      <Action>
-        1. Propose scope-type with rationale.
-        2. Outline the section set per `AX_SCOPE_TYPE_BRANCH`.
-        3. Approval Check. STOP.
-        Confirmed → STEP_2.
-      </Action>
-    </Step>
-
-    <Step id="STEP_2_INTENT_CAPTURE">
-      <Goal>Lock the scope's goal and primary constraints.</Goal>
-      <Action>
-        1. Intent Candidate: 1–3 bullets.
-        2. Evidence Hygiene per `AX_EVIDENCE_HYGIENE`: Facts / Assumptions / Hypotheses, separated.
-        3. Questions: 2–5; ≥1 uncomfortable per `AX_UNCOMFORTABLE_QUESTIONS`.
-        4. For product / library: capture initial Runtime Backing posture per `AX_RUNTIME_BACKING_EXPLICIT`.
-        5. Phase Progress + Approval Check. STOP.
-      </Action>
-    </Step>
-
-    <Step id="STEP_3_TYPE_SPECIFIC_A">
-      <Goal>First type-specific step.</Goal>
-      <Action>
-        Per `AX_SCOPE_TYPE_BRANCH`:
-        - infrastructure → Tool Categories Declaration. Approval Check. STOP.
-        - contracts → Interface Declaration (schema format, versioning scheme, namespacing). Approval Check. STOP.
-        - library → Requirements Gate (Functional, Non-Functional, Out-of-Scope, Rules). Approval Check. STOP.
-        - product → Requirements Gate (Functional, Non-Functional, Out-of-Scope, Runtime Backing per `AX_RUNTIME_BACKING_EXPLICIT`, Project-Wide Rules). Approval Check. STOP.
-      </Action>
-    </Step>
-
-    <Step id="STEP_4_TYPE_SPECIFIC_B">
-      <Goal>Second type-specific step.</Goal>
-      <Action>
-        Per `AX_SCOPE_TYPE_BRANCH`:
-        - infrastructure → Tool Choices (2–3 candidates per category; Mandatory Rationale Pull; Decision Log entry per tool). Tool Interaction Check. STOP.
-        - contracts → Versioning Policy (semver / date-based; breaking-change protocol; consumer notification). STOP.
-        - library → Golden DX (Public API DX per `AX_DX_FIRST`). STOP.
-        - product → Golden DX per `AX_DX_FIRST`. STOP.
-      </Action>
-    </Step>
-
-    <Step id="STEP_5_TYPE_SPECIFIC_C">
-      <Goal>Third type-specific step.</Goal>
-      <Action>
-        Per `AX_SCOPE_TYPE_BRANCH`:
-        - infrastructure → Developer Workflow Example. STOP.
-        - contracts → Compatibility Matrix (backward-compat guarantees; consumers list). STOP.
-        - library → Architecture (Public Surface structure, key design patterns, brief rejected alternatives). Approval Check. STOP.
-        - product → Design Variants 2–3 (depth per Project Type). Approval Check. STOP.
-      </Action>
-    </Step>
-
-    <Step id="STEP_6_TYPE_SPECIFIC_D">
-      <Goal>Fourth type-specific step (only some types).</Goal>
-      <Action>
-        Per `AX_SCOPE_TYPE_BRANCH`:
-        - infrastructure → File Structure (repo root layout; config file mapping). Then Effective Rules table. Then Verification Commands table (mandatory — one row per active tool command). STOP.
-        - contracts → skip, proceed to STEP_7.
-        - library → skip, proceed to STEP_7.
-        - product → Architecture Choice (operator picks variant; Mandatory Rationale Pull; Decision Log entry). STOP.
-      </Action>
-    </Step>
-
-    <Step id="STEP_7_EXTERNAL_DEPENDENCIES_AUDIT">
-      <Goal>Reconcile the drafted spec with repository reality. Surface every external assumption the spec makes, classify each as exists / missing / unknown, resolve unknowns with the operator, and materialize Bootstrap Requirements.</Goal>
-      <Action>
-        1. **Walk the drafted spec end-to-end** (all sections produced by STEP_3–STEP_6). Extract every external assumption — anything the spec references that must exist before functional tasks can run. Cover all of:
-           - Third-party packages (npm / pip / cargo / etc.) — name + intended version constraint.
-           - Workspace links / monorepo packages — internal scope this scope depends on.
-           - Runtime tools (CLIs, binaries, language runtimes).
-           - Files and paths the spec assumes pre-exist (`package.json`, config files, fixtures).
-           - Types / modules / contracts sourced from other scopes (resolve via Scope Dependencies).
-           - Environment variables, secrets, external services (DBs, queues, APIs).
-           - Repo-level structural prerequisites (a package boundary, a workspace entry, a folder).
-        2. **Classify each assumption** as `exists` | `missing` | `unknown`:
-           - For verification, narrow Read is permitted **only for inventory** (`package.json`, `tsconfig.json`, `specs/README.md`, scope manifests, filesystem checks). Reading application source code for inspiration is forbidden — `AX_SPEC_IS_SOLE_SOURCE` still holds for design content.
-           - `exists` → record actual location / version / scope ref.
-           - `missing` → assumption is real and known to be absent.
-           - `unknown` → cannot be determined from repo alone.
-        3. **Resolve every `missing` and `unknown` with the operator.** For each, ask explicitly:
-           - source (which registry / which scope / which operator action),
-           - version / shape constraint,
-           - owner (this scope's bootstrap task vs external prerequisite vs operator-side action outside SDD).
-           Record each resolution as a Decision Log entry.
-        4. **Materialize Bootstrap Requirements** in the spec. Ordered list — each item:
-           | Requirement | Kind | Owner | Resolution |
-           Kind ∈ `package` | `workspace-link` | `tool` | `file` | `external-type` | `env` | `service` | `structural`.
-           Owner ∈ `this-scope-task` | `external-prereq-scope` | `operator-action`.
-           Resolution ∈ verbatim outcome from step 3 (e.g. `install valibot@^0.42 via npm`, `link @org/contracts via workspace`, `operator provisions DATABASE_URL`).
-
-           Note: missing rule files (under `ai/directives/**`) are NOT bootstrap rows — they are knowledge artifacts handled inline in STEP_3–6 per `AX_SCOPE_RULES_DECLARATION`, not external assumptions to install.
-        5. **Gate.** Discovery cannot proceed to STEP_8 until Bootstrap Requirements exists. Empty list is acceptable only when steps 1–3 produced zero external assumptions — an explicit «nothing to bootstrap», not an omission. Otherwise → `H_BOOTSTRAP_REQUIREMENTS_MISSING`.
-
-        **Scope of this step:** verification of physical/external prerequisites only. This step does NOT revisit functional design — Vision, Requirements, Architecture, Contracts are immutable here. If a bootstrap finding invalidates a design decision, pop back to the relevant STEP_3–STEP_6 explicitly and treat as `pivot` per `AX_PIVOT_REQUIRES_SUPERSESSION`.
-      </Action>
-    </Step>
-
-    <Step id="STEP_8_FINAL_SPEC">
-      <Goal>Emit the scope spec.</Goal>
-      <Action>
-        1. Assemble `specs/<scope-name>/<scope-name>.spec.md` per the corresponding SPEC_CONTRACT. The Bootstrap Requirements section produced in STEP_7 is part of every spec regardless of scope-type.
-        2. In `pivot` mode: include Pivot Invalidation List (per `AX_PIVOT_REQUIRES_SUPERSESSION`); emit rework-flavored Decision Log entries per `REWORK_DECISION_LOG_ENTRY_FORMAT`.
-        3. Output for review. Approval Check. STOP.
-      </Action>
-    </Step>
-  </Execution_Plan>
-
-  <Frame_Rules>
-    <Rule id="FRAME_PUSH_WHEN">Push a frame on: dispute about scope-type; alternative tool / architecture proposal; sub-topic that cannot close in one sentence; uncomfortable-question dive; pivot rationale clarification.</Rule>
-    <Rule id="FRAME_POP_WHEN">Pop on: confirmed local conclusion; deferred non-blocking topic; topic requires a separate supporting artifact while main flow continues.</Rule>
-    <Rule id="FRAME_STATUS_VALUES">OPEN | BLOCKED | READY_TO_RETURN | READY_TO_ADVANCE | DEFERRED.</Rule>
-    <Rule id="RETURN_SUMMARY_FORMAT">On pop, emit a Return Summary with: Confirmed / Changed / New Constraints / Open / Parent Next.</Rule>
-  </Frame_Rules>
-
-  <Example_Patterns>
-    Discovery deliberately avoids one monolithic Golden Example — scope-spec shape varies too much across scope-types. Below are intentionally compact, freeform sketches; treat them as orientation, not templates. The normative shapes live in the SPEC_STRUCTURE contracts.
-
-    <Pattern id="EXAMPLE_INFRASTRUCTURE">
-      ```markdown
-      # infra-base: Infrastructure Specification
-
-      ## 1. Vision
-      Минимальный TS-стек: быстрый CI, deterministic install, zero-config formatter.
-
-      ## 2. Tool Stack
-      | Category | Tool | Rationale |
-      |---|---|---|
-      | package-management | pnpm | D-001 (lockfile determinism vs npm) |
-      | type-check | tsc | D-002 (no transpiler — esbuild на bundler-этапе) |
-      | linting+formatting | biome | D-003 (один tool вместо eslint+prettier) |
-
-      ## 3. Dev Workflow Example
-      ```bash
-      pnpm install
-      pnpm typecheck && pnpm test && pnpm lint
-      ```
-
-      ## 5. Effective Rules (cascade)
-      | Rule | Category | File | Source |
-      |---|---|---|---|
-      | <rule-id> | coding | ai/directives/coding/<rule>.xml | infra (D-NNN) |
-      | <rule-id> | infra | ai/directives/infra/<rule>.xml | infra (D-NNN) |
-      ```
-    </Pattern>
-
-    <Pattern id="EXAMPLE_CONTRACTS">
-      ```markdown
-      # api-contracts: Contracts Specification
-
-      ## 2. Interface Declaration
-      - Schema format: OpenAPI 3.1
-      - Versioning: date-based (`/v2026-05-01/...`)
-      - Namespace: `api.example.com`
-
-      ## 3. Versioning Policy
-      Breaking changes требуют новой date-версии + 6 мес deprecation окна; non-breaking — same version, additive only.
-
-      ## 4. Compatibility Matrix
-      | Consumer | Min version | Breaking protocol |
-      |---|---|---|
-      | backend | 2026-05-01 | dual-publish on transition |
-      | web | 2026-05-01 | client codegen via openapi-typescript |
-      ```
-    </Pattern>
-
-    <Pattern id="EXAMPLE_LIBRARY">
-      ```markdown
-      # logger-core: Library Specification
-
-      ## 2. Approved Golden DX Example
-      ```ts
-      // happy path
-      const log = createLogger({ name: 'payments', level: 'info' })
-      log.info({ orderId }, 'charge succeeded')
-
-      // degradation: transport unavailable
-      log.transport.on('error', (err) => log.warn({ err }, 'fallback to stdout'))
-      ```
-
-      ## 4. Public API Surface
-      - `createLogger(config) → Logger`
-      - `Logger.{ trace, debug, info, warn, error, fatal }(payload, message)`
-      - `Logger.child(bindings) → Logger`
-      ```
-    </Pattern>
-
-    <Pattern id="EXAMPLE_PRODUCT">
-      ```markdown
-      # backend: Scope Specification
-
-      ## 2. Project Type
-      - Type: service-module-sdk
-      - Why: IMAP backend, без UI; transport — long-lived TCP + outbound HTTP.
-
-      ## 3. Approved Golden DX Example (UX-flow)
-      Сценарий «новое письмо»: IMAP IDLE keep-alive ловит EXISTS → forward to consumer → ack;
-      degradation: server reset → exponential backoff + restore по UIDVALIDITY.
-
-      ## 4.4 Runtime Backing & Deferred Scope
-      - IMAP IDLE: `real-runtime` (production-critical).
-      - OAuth refresh: `real-runtime`.
-      - Webhook dispatcher: `simulation` в v1 (deferred → TSK-stub до реальной integration).
-      ```
-    </Pattern>
-  </Example_Patterns>
-
-  <Output_Contracts>
-    <Contract id="TRACE_HEADER_FORMAT">
-      ```text
-      🦾 DSC_R<N> | SCOPE: <scope-name> | TYPE: <scope-type> | MODE: <greenfield|refine|pivot> | STACK: ROOT__<FRAME>__<SUBFRAME> | FRAME: F_<KEY>_R<N> | <STATUS> | CONF: <LOW|MEDIUM|HIGH>
-      🎯 GOAL: <local goal>
-      ⏭️ EXIT: <exit condition>
-      ```
-    </Contract>
-
-    <Contract id="INFRASTRUCTURE_SPEC_STRUCTURE">
-      Every top-level `## N.` section is wrapped with `<!--SECTION:UPPER_SNAKE-->…<!--/SECTION:UPPER_SNAKE-->` markers so any agent can pull a single section via `~/.claude/skills/sdd-execute/scripts/sdd extract <file> <NAME>`. Open marker IMMEDIATELY before the header; close marker IMMEDIATELY before the next same-level header (or EOF). Sub-sections (`### N.M`) and entity-level headers are NOT wrapped — they live inside the containing anchor. Section names are author-discretionary (the four templates below illustrate idiomatic choices); no name registry is enforced. Grammar source of truth: `extract-section.sh`. The four `SPEC_STRUCTURE` templates emit anchors by default — copy verbatim.
-
-      ```markdown
-      # <scope-name>: Infrastructure Specification
-
-      <!--SECTION:SCOPE_TYPE-->
-      ## scope-type
-      infrastructure
-      <!--/SECTION:SCOPE_TYPE-->
-
-      <!--SECTION:VISION-->
-      ## 1. Vision
-      [Что включает dev/ops experience.]
-      <!--/SECTION:VISION-->
-
-      <!--SECTION:TOOL_STACK-->
-      ## 2. Tool Stack
-
-      ### 2.1 Categories Covered
-      [Список категорий + краткое обоснование исключений.]
-
-      ### 2.2 Tool Choices
-      | Category | Tool | Rationale |
-      |---|---|---|
-      | <category> | <tool> | D-NNN |
-      <!--/SECTION:TOOL_STACK-->
-
-      <!--SECTION:WORKFLOW_EXAMPLE-->
-      ## 3. Developer Workflow Example
-      [Shell-script: setup, daily flow, commit flow, debug flow.]
-      <!--/SECTION:WORKFLOW_EXAMPLE-->
-
-      <!--SECTION:FILE_STRUCTURE-->
-      ## 4. File Structure
-      [ASCII tree + File Mapping.]
-      <!--/SECTION:FILE_STRUCTURE-->
-
-      <!--SECTION:EFFECTIVE_RULES-->
-      ## 5. Effective Rules (for cascade)
-      | Rule | Category | Source |
-      |---|---|---|
-      | <rule-name> | coding | infra (D-NNN) |
-      <!--/SECTION:EFFECTIVE_RULES-->
-
-      <!--SECTION:VERIFICATION_COMMANDS-->
-      ## 6. Verification Commands
-      **Mandatory for infrastructure scopes.** After tool stack is finalized, record a table:
-      | Command Name      | Invocation          |
-      | typecheck-command | <actual invocation> |
-      | test-command      | <actual invocation> |
-      | lint-command      | <actual invocation> |
-      | format-command    | <actual invocation> |
-      | check-command     | <actual invocation> |
-
-      Include only command names for tools present in the chosen stack.
-      `check-command` is **always required** when the runtime setup rule (`nodejs-npm-setup` or equivalent) is active — it is the composed entry point that runs all active phases in `CheckPhaseOrder` order (typecheck → test → lint → format). Composition: chain invocations of each active phase command in that order. Task tickets use `check-command` as their single verification alias.
-      <!--/SECTION:VERIFICATION_COMMANDS-->
-
-      <!--SECTION:DECISION_LOG-->
-      ## 7. Decision Log
-      [D-NNN entries.]
-      <!--/SECTION:DECISION_LOG-->
-
-      <!--SECTION:SCOPE_DEPENDENCIES-->
-      ## 8. Scope Dependencies
-      - **Depends on:** None (infrastructure scopes are typically leaves)
-      - **Provides rules to:** [list of product/library scopes that depend on this]
-      <!--/SECTION:SCOPE_DEPENDENCIES-->
-
-      <!--SECTION:BOOTSTRAP_REQUIREMENTS-->
-      ## 9. Bootstrap Requirements
-      | Requirement | Kind | Owner | Resolution |
-      |---|---|---|---|
-      <!-- Kind ∈ package | workspace-link | tool | file | external-type | env | service | structural -->
-      <!-- Owner ∈ this-scope-task | external-prereq-scope | operator-action -->
-      <!-- Empty list allowed only when STEP_7 audit produced zero external assumptions — declare it explicitly: "No external bootstrap required." -->
-      <!--/SECTION:BOOTSTRAP_REQUIREMENTS-->
-
-      <!--SECTION:HANDOFF-->
-      ## 10. Handoff
-      - **Setup tasks to scaffold:** [list]
-      - **Effective rules ready for cascade:** see 5
-      - **Verification Commands ready for cascade:** see 6
-      - **Bootstrap tickets ready for cascade:** see 9
-      - **Open risks:** [not-closed items]
-
-      <!-- 10.1 Pivot Invalidation List — only in pivot mode -->
-      <!--/SECTION:HANDOFF-->
-      ```
-    </Contract>
-
-    <Contract id="CONTRACTS_SPEC_STRUCTURE">
-      ```markdown
-      # <scope-name>: Contracts Specification
-
-      <!--SECTION:SCOPE_TYPE-->
-      ## scope-type
-      contracts
-      <!--/SECTION:SCOPE_TYPE-->
-
-      <!--SECTION:VISION-->
-      ## 1. Vision
-      [Что контракт определяет и для кого.]
-      <!--/SECTION:VISION-->
-
-      <!--SECTION:INTERFACE_DECLARATION-->
-      ## 2. Interface Declaration
-      - **Schema format:** OpenAPI 3.x | gRPC proto3 | JSON Schema | GraphQL SDL
-      - **Versioning scheme:** semver | date-based (YYYY-MM-DD) | none
-      - **Namespace:** <api prefix / package name>
-      - **Interfaces:** [список endpoint groups / message types / operations]
-      <!--/SECTION:INTERFACE_DECLARATION-->
-
-      <!--SECTION:VERSIONING_POLICY-->
-      ## 3. Versioning Policy
-      [Semver rules / breaking-change protocol / deprecation window.]
-      <!--/SECTION:VERSIONING_POLICY-->
-
-      <!--SECTION:COMPATIBILITY_MATRIX-->
-      ## 4. Compatibility Matrix
-      | Consumer scope | Min compatible version | Breaking change protocol |
-      |---|---|---|
-      <!--/SECTION:COMPATIBILITY_MATRIX-->
-
-      <!--SECTION:DECISION_LOG-->
-      ## 5. Decision Log
-      [D-NNN entries.]
-      <!--/SECTION:DECISION_LOG-->
-
-      <!--SECTION:SCOPE_DEPENDENCIES-->
-      ## 6. Scope Dependencies
-      - **Depends on:** [infra scopes if any]
-      - **Provides contracts to:** [product/library scopes]
-      <!--/SECTION:SCOPE_DEPENDENCIES-->
-
-      <!--SECTION:BOOTSTRAP_REQUIREMENTS-->
-      ## 7. Bootstrap Requirements
-      | Requirement | Kind | Owner | Resolution |
-      |---|---|---|---|
-      <!-- Empty list allowed only when STEP_7 audit produced zero external assumptions — declare explicitly. -->
-      <!--/SECTION:BOOTSTRAP_REQUIREMENTS-->
-
-      <!--SECTION:HANDOFF-->
-      ## 8. Handoff
-      - **Contract files to scaffold:** [schema files, codegen configs]
-      - **Bootstrap tickets ready for cascade:** see 7
-      - **Open risks:** [versioning gaps, unconfirmed consumers]
-      <!--/SECTION:HANDOFF-->
-      ```
-    </Contract>
-
-    <Contract id="LIBRARY_SPEC_STRUCTURE">
-      ```markdown
-      # <scope-name>: Library Specification
-
-      <!--SECTION:SCOPE_TYPE-->
-      ## scope-type
-      library
-      <!--/SECTION:SCOPE_TYPE-->
-
-      <!--SECTION:VISION-->
-      ## 1. Vision & Primary Goal
-      [Что library делает; главная проблема, которую решает.]
-      <!--/SECTION:VISION-->
-
-      <!--SECTION:GOLDEN_DX-->
-      ## 2. Approved Golden DX Example
-      [Публичный API DX: init/setup + happy path + error path. Комментарии раскрывают намерение.]
-      <!--/SECTION:GOLDEN_DX-->
-
-      <!--SECTION:REQUIREMENTS_AND_CONSTRAINTS-->
-      ## 3. Requirements & Constraints
-
-      ### 3.1 Functional Requirements
-
-      ### 3.2 Non-Functional Constraints
-
-      ### 3.3 Out-of-Scope
-
-      ### 3.4 Runtime Backing & Deferred Scope
-      [Per `AX_RUNTIME_BACKING_EXPLICIT`. Posture per major capability + deferred parts.]
-
-      ### 3.5 Rules
-      | Rule | Category | Source |
-      |---|---|---|
-      <!--/SECTION:REQUIREMENTS_AND_CONSTRAINTS-->
-
-      <!--SECTION:PUBLIC_API_SURFACE-->
-      ## 4. Public API Surface
-      [Ключевые exported interfaces, types, functions. Intent-level, без impl detail.]
-      <!--/SECTION:PUBLIC_API_SURFACE-->
-
-      <!--SECTION:ARCHITECTURE-->
-      ## 5. Architecture
-      [Выбранный design pattern. Кратко — rejected alternatives.]
-      <!--/SECTION:ARCHITECTURE-->
-
-      <!--SECTION:DECISION_LOG-->
-      ## 6. Decision Log
-      [D-NNN entries.]
-      <!--/SECTION:DECISION_LOG-->
-
-      <!--SECTION:SCOPE_DEPENDENCIES-->
-      ## 7. Scope Dependencies
-      - **Depends on:** [infra-*, contracts scopes]
-      - **Provides to:** [consumer scopes]
-      <!--/SECTION:SCOPE_DEPENDENCIES-->
-
-      <!--SECTION:BOOTSTRAP_REQUIREMENTS-->
-      ## 8. Bootstrap Requirements
-      | Requirement | Kind | Owner | Resolution |
-      |---|---|---|---|
-      <!-- Empty list allowed only when STEP_7 audit produced zero external assumptions — declare explicitly. -->
-      <!--/SECTION:BOOTSTRAP_REQUIREMENTS-->
-
-      <!--SECTION:HANDOFF-->
-      ## 9. Handoff to module-decomposition
-      - **Areas requiring decomposition:** [list]
-      - **Named abstractions:** [from Golden DX]
-      - **Bootstrap tickets ready for cascade:** see 8
-      - **Open risks:** [validation needs]
-
-      <!-- 9.1 Pivot Invalidation List — only in pivot mode -->
-      <!--/SECTION:HANDOFF-->
-      ```
-    </Contract>
-
-    <Contract id="PRODUCT_SPEC_STRUCTURE">
-      ```markdown
-      # <scope-name>: Scope Specification
-
-      <!--SECTION:SCOPE_TYPE-->
-      ## scope-type
-      product
-      <!--/SECTION:SCOPE_TYPE-->
-
-      <!--SECTION:VISION-->
-      ## 1. Vision & Primary Goal
-      <!--/SECTION:VISION-->
-
-      <!--SECTION:PROJECT_TYPE-->
-      ## 2. Project Type
-      - **Type:** app[mobile|desktop|spa] | service-module-sdk | cli-utility
-      - **Why this type:** [Краткое обоснование.]
-      <!--/SECTION:PROJECT_TYPE-->
-
-      <!--SECTION:GOLDEN_DX-->
-      ## 3. Approved Golden DX Example
-      [Commentary-rich: init/setup + happy path + error/degradation path.]
-      <!--/SECTION:GOLDEN_DX-->
-
-      <!--SECTION:REQUIREMENTS_AND_CONSTRAINTS-->
-      ## 4. Requirements & Constraints
-
-      ### 4.1 Functional Requirements
-
-      ### 4.2 Non-Functional Constraints
-
-      ### 4.3 Out-of-Scope
-
-      ### 4.4 Runtime Backing & Deferred Scope
-      [Per `AX_RUNTIME_BACKING_EXPLICIT`. Posture per major capability + deferred parts + trust boundaries требующие real runtime hook.]
-
-      ### 4.5 Rules
-      | Rule | Category | Source |
-      |---|---|---|
-      <!--/SECTION:REQUIREMENTS_AND_CONSTRAINTS-->
-
-      <!--SECTION:ARCHITECTURE-->
-      ## 5. High-Level Architecture
-      [Выбранный вариант. Block diagram. Краткие описания.]
-
-      ### 5.1 Rejected Alternatives
-      <!--/SECTION:ARCHITECTURE-->
-
-      <!--SECTION:DECISION_LOG-->
-      ## 6. Decision Log
-      [D-NNN entries.]
-      <!--/SECTION:DECISION_LOG-->
-
-      <!--SECTION:SCOPE_DEPENDENCIES-->
-      ## 7. Scope Dependencies
-      - **Depends on:** [infra-*, api-contracts, design-system-* scopes]
-      - **Provides to:** [consumer scopes, if any]
-      <!--/SECTION:SCOPE_DEPENDENCIES-->
-
-      <!--SECTION:BOOTSTRAP_REQUIREMENTS-->
-      ## 8. Bootstrap Requirements
-      | Requirement | Kind | Owner | Resolution |
-      |---|---|---|---|
-      <!-- Empty list allowed only when STEP_7 audit produced zero external assumptions — declare explicitly. -->
-      <!--/SECTION:BOOTSTRAP_REQUIREMENTS-->
-
-      <!--SECTION:MODULE_MAP-->
-      ## 9. Module Map
-      [Appended by `module-decomposition`. Initially: «Modules not yet decomposed — run `module-decomposition <scope-name>`».]
-      <!--/SECTION:MODULE_MAP-->
-
-      <!--SECTION:HANDOFF-->
-      ## 10. Handoff to module-decomposition
-      - **Primary input:** `specs/<scope-name>/<scope-name>.spec.md`
-      - **Areas requiring decomposition:** [list]
-      - **Named abstractions:** [from Golden DX]
-      - **Bootstrap tickets ready for cascade:** see 8
-      - **Open risks:** [validation needs]
-
-      <!-- 10.1 Pivot Invalidation List — only in pivot mode -->
-      <!--/SECTION:HANDOFF-->
-      ```
-    </Contract>
-
-    <Contract id="DECISION_LOG_ENTRY_FORMAT">
-      ```markdown
-      ### D-NNN — <short title>
-      - **Status:** active | superseded | rejected | deferred
-      - **Recorded:** session Discovery, <scope-name>
-      - **Why:** <operator's own wording>
-      - **Risk accepted:** <if any>
-      - **Rejected alternatives:** <list>
-      - **Supersedes:** D-NNN (when superseding)
-      ```
-    </Contract>
-
-    <Contract id="REWORK_DECISION_LOG_ENTRY_FORMAT">
-      Used in `pivot` mode for each replaced decision. Self-contained: a future reader of the spec at this git ref must understand the rework without external context.
-
-      ```markdown
-      ### D-NNN — <short title> (rework)
-      - **Status:** active
-      - **Recorded:** session Discovery, <scope-name>, pivot
-      - **Supersedes:** D-MMM
-      - **Pre-rework state:** git ref `<sha-or-tag>` (snapshot of spec immediately before this pivot)
-      - **Was:** <one-sentence summary of the prior decision>
-      - **Now:** <one-sentence summary of the replacement>
-      - **Why:** <operator's own wording — what forced the rework>
-      - **Risk accepted:** <if any>
-      - **Downstream invalidation:** see Pivot Invalidation List
-      ```
-
-      Paired with Pivot Invalidation List entries that enumerate concrete downstream artifacts (`refine-module` targets, ticket reopens, rule revisits) for `audit` (`AX_STALE_AFTER_PIVOT_VERIFICATION`).
-    </Contract>
-
-    <Contract id="PIVOT_INVALIDATION_LIST_FORMAT">
-      ```markdown
-      ### 9.1 Pivot Invalidation List
-      - **Module specs requiring refine:** [list with reasons]
-      - **Tasks requiring reopen:** [TSK-NN — reason]
-      - **Rules to revisit:** [list]
-      ```
-    </Contract>
-  </Output_Contracts>
-</SddDiscovery>