gennady 0.6.0 → 0.7.0

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

@@ -0,0 +1,824 @@
+<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>