Turn the approved scope spec into a hierarchy of module specs with a complete entity inventory, an explicit public surface for every entity, strict DbC contracts, and a designed file structure. Second scope session. Input — `specs//.spec.md` from Discovery. Only applicable to scope-type=product and scope-type=library. Output: - hierarchy of `specs///.spec.md` (nesting allowed for nested modules); - scope spec 8 Module Map updated (append-only per module row); - module spec 1 links back to `../../.spec.md`. Out of scope here: task tickets, BDD scenarios, execution plans, coding/testing rules linkage — those belong to `task-scaffolding`. **Glossary.** Second scope session. Phase agent = subagent under `phase-execution-protocol` (phase 4, dispatched by `sdd-execute` orchestrator). Scaffolder = `task-scaffolding` agent (phase 3, consumes these specs). scope-type ∈ {product, library} — this directive is NOT applicable to infrastructure or contracts scopes. **Three modes, auto-detected from intake:** - `initial` — first run, only scope spec exists, no module specs. - `add-module` — add new module to existing tree without touching others. - `refine-module` — refine an existing module (typically triggered by Discovery's Pivot Invalidation List or audit `INSIGHT_BACKFLOW`). Mode controls step branching and which axioms apply. Mode is mechanical; ambiguity halts. | Intake | Verb | Mode | |---|---|---| | Scope spec only, no module specs | — | `initial` | | Module specs exist | add module X / новый модуль | `add-module` (operator must name) | | Module specs exist | refine X / уточни / поправь | `refine-module` (operator must name) | | Module specs exist + Pivot Invalidation List | — | `refine-module` (target named in list) | | Module specs exist | none of the above | HALT, ask operator | | No scope spec link | — | HALT, require Discovery's spec | Module decomposition applies ONLY to scope-type=product and scope-type=library. - scope-type=infrastructure → `H_INVALID_SCOPE_TYPE` (use discovery for infrastructure scopes; they have their own Effective Rules section). - scope-type=contracts → `H_INVALID_SCOPE_TYPE` (contracts scopes define interfaces, not modules). **Phase reads specs only, never code, never project-wide search (grep / find / ripgrep).** Allowed inputs by mode: - `initial` — scope spec (`specs//.spec.md`) + rule files at `ai/directives//.xml`. - `add-module` / `refine-module` — scope spec + relevant existing module specs + rule files. Optional supporting artifacts if operator passes them. Spec/code mismatch is resolved by `audit` (only directive that compares spec against code). **Two stages: pick rules, then walk through axioms. Never activate silently.** - **Stage A — Relevance per category.** Shortlist «recommend activate» + «considered, recommend skip», each with one-line rationale scoped to module context. Operator agree / expand / contract → list locked; deviations → Module Decision Log. - **Stage B — Per-rule axiom walk-through (infra rules only).** Read only `Mission`, `Belief_State`, `Reward_Criteria` of the rule file. Surface each axiom with rationale → operator Accept (default) / Adapt (Decision Log) / Override (Decision Log). No badgering on uncontroversial axioms. **Loading defaults at module level.** `architecture/*`, `infra/*` → walk through now (Stage B). `coding/*`, `testing/*` → deferred — phase-subagent loads them at phase entry per `phase-execution-protocol` (Stage A only at this phase). Activation outcomes recorded in 8 Module Decision Log of the relevant module spec. In `add-module` mode existing module specs are NOT touched. Only: - new `specs///.spec.md`; - scope spec 8 Module Map: APPEND new module row (append at end). Other rows untouched; - scope spec Golden DX Example: rewritten as composition view per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP` (the ONE exception to «other scope-spec sections untouched»). Touching another module's spec in `add-module` is forbidden. If sibling changes are needed, run `module-decomposition` again in `refine-module` mode for that specific module. `module-decomposition` owns TWO sections in the scope spec (`specs//.spec.md`): - **Module Map** (`## 8. Module Map`) — append-only rows per module. - **Golden DX Example** (`## 2.` library / `## 3.` product) — composition view. Every module-decomposition session (`initial` / `add-module` / `refine-module`) rewrites this section as one user-facing flow over the current module set. Module-level snippets NOT inlined — anchor-link to each module's `## 2. Module Usage Example`. Skip rewrite only when scope has zero modules with public surface. **Bidirectional consistency check** before session close — both directions must pass: - (→) every named abstraction in scope-spec Golden DX has a home in some module's `## 3. Entity Inventory`; - (←) every module with public surface (≥1 entry in `## 4. Entity Surfaces`) either appears in scope-spec Golden DX OR carries `internal-only — not in composition view` in its `## 8. Module Decision Log`. Failure of either direction → fix the gap before STEP_6 finishes; do NOT close session with inconsistency. All other scope-spec sections (Vision, Requirements & Constraints, Architecture, Decision Log, Handoff) remain untouched. Cross-scope module dependencies → `Scope Reference` in module-spec `## 9. Inter-Module Dependencies`, never a direct reference to another product scope's modules. `module-decomposition` does NOT write to `specs/README.md` (that is `setup`'s sole property). In `refine-module` mode existing public surface is preserved unless explicitly retired with operator approval. Refinement = adding entities, tightening contracts (preconditions can become stricter, postconditions cannot become weaker), or fixing wrong details. Removing a public entity or weakening postconditions is a breaking change requiring a Decision Log entry with operator-confirmed `Risk accepted`. Refinement preserves the Entity Inventory closed-world commitment: post-refinement inventory is still complete. New entities go into the inventory in the same session. Module spec body is reworked in place where needed; full predecessor state lives in git history. Main path: `INTAKE → MODULE_MAP → ENTITY_INVENTORY → ENTITY_SURFACE → CONTRACTS_DBC → FILE_STRUCTURE → FINAL_HIERARCHY`. Per-module phases iterate: complete a phase across all modules before moving to the next. Compact header on every message. Global: `DM_R001`, `DM_R002`, … Frame: `F_MM_R01` (module map), `F_EI__R01` (entity inventory), `F_ES___R01` (entity surface), `F_DBC__R01`, `F_FS__R01`, `F_FH_R01`. ASCII uppercase + digits + `_` only. Every frame has an exit condition. Status: OPEN | BLOCKED | READY_TO_RETURN | READY_TO_ADVANCE | DEFERRED. Indefinite drilling without local result is forbidden. Sub-topic that does not block current phase → DEFERRED, return to parent. Module boundaries are decided by the operator. The agent proposes 2–3 decomposition variants along different axes (by feature, by layer, by data ownership, by lifecycle). No unilateral pick. Final decomposition recorded in scope spec's Decision Log: which axis was chosen and why. Hierarchy, not flat list. Sub-modules → nested structure: `specs////.spec.md`. Depth unlimited; each level must be justified — nesting for its own sake is forbidden. All specs are cross-linked. Entity inventory is a closed world. For every module the agent lists ALL entities explicitly. Phrases like «и т.д.», «etc.», «and similar» are forbidden. Before approval, the agent makes the explicit drift-commitment captured in `ENTITY_INVENTORY_FORMAT`. Entity surface is exhaustive per `ENTITY_SURFACE_FORMAT`: Type, Public Properties, Public Operations (intent-level, no language signatures), Lifecycle, Events, Errors & Degradation, Consumers. No private detail — that is Executor's job. No consumer — no component (YAGNI). Every entity has explicit `Consumers`: - Internal: future file path or another inventory entity name. - External: textual description (CLI, External API, Browser, OS Event Bus, …). Consumer is «future feature» without v1-scope confirmation → entity removed or marked `deferred`. - Business logic depends on Ports, not Adapters. Preconditions / postconditions / invariants live on Ports. Adapters reference a Port and describe side effects + runtime backing + verification levels. - Port introduced only with confirmed v1 variability (≥2 implementations) or explicit test seam. Single implementation without confirmed split → Service or Entity, not Port. - Every proposed abstraction requires justification: which current risk / constraint / consumer it closes. - **DbC section shape is flexible.** `## 5. Module Contracts (DbC)` carries any subset of subsections drawn from the entity Type vocabulary (Port, Adapter, Service, Pattern, Utility, Module-level invariants, …). Ports/Adapters are AVAILABLE, not mandatory: single-implementation modules legitimately use Service-only or Pattern-only DbC. Subsection numbering is optional (`### 5.0`, `### 5.1`, …, or unnumbered `### OperationDef Pattern`). DbC is derived from context, not only from DX code. Scope spec 4 Requirements & Constraints is mandatory source for preconditions, invariants, fallback semantics, trust boundaries. A contract cannot be reduced to «what to do» while ignoring «under what conditions it must not». Contracts are language-agnostic. No language-specific syntax in DbC. Vocabulary: Port, Adapter, Entity, Command, Query, Event. Concrete signatures belong to Executor. Single namespace for grepability. Module-wide: `` / ``. Files: `-*.`. Types/classes/constants: `*`. Platform-specific: `--*.`, `*`. Goal: `rg ` or `rg -` finds all related code. No God Objects. File size ≤1500 lines. File structure (phase `FILE_STRUCTURE`) physically separates `ports/` (or `contracts/`) from `adapters/` (or `impl/`). Runtime backing and verification levels in every contract that depends on platform/runtime hooks. Two orthogonal axes: - `Runtime Backing` (single value): `not-implemented` | `simulation` | `real-runtime`. What's actually behind the public surface in production code. - `Verification Levels` (multi-value): subset of `contract` | `unit` | `integration` | `e2e`. - `Deferred Runtime Scope` (if part of declared behavior is not yet backed by real runtime). Simulation must not masquerade as runtime: declaring `real-runtime` while the implementation is simulation-only without explicit `Deferred Runtime Scope` is forbidden. Public options cannot be silently forgotten. All include flags, transport settings, platform-specific options mentioned in scope spec must either bind to a concrete Port/Adapter contract or be explicitly marked `deferred / not consumed in v1` with a pointer to the task or version that activates them. Module-level decisions → module Decision Log. Cross-module or system-level → scope spec's Decision Log. Mandatory triggers: chosen decomposition axis; choice of Port vs Service for an entity with confirmed variability; accepted runtime-backing risk; adapter choice diverging from industry standard; change/cancellation of a prior decision. Format: see `DECISION_LOG_ENTRY_FORMAT`. Separate Facts / Assumptions / Hypotheses. - Facts — directly in scope spec. - Assumptions — working assumptions needing confirmation. - Hypotheses — conjectures requiring operator validation. Index questions with `Q_:`. Categories: `MM` (module map), `EI` (entity inventory), `ES` (entity surface), `DBC`, `FS` (file structure), `CONS` (consumer), `RUNTIME`, `RISK`. UPPER_SNAKE_CASE; collision → suffix `_2`, `_3`. Hidden assumptions break the model. In every meaningful frame ask: canonical source of truth for this entity? degradation when dependency unavailable? where is runtime simulation? who validates input at this boundary? trust boundary between two modules? YAGNI. Every module, entity, Port has explicit v1 consumer or near-term variability. Future-proofing without a confirmed consumer is forbidden. - Phase agreement: agent never closes a phase autonomously; signals `STATUS=READY_TO_ADVANCE`; operator confirms. Phase Progress every meaningful round with per-module / per-entity counters («5/12 entities approved in module X»). - Neutral + critical: no auto-agree. Every operator proposal — check vs scope spec + locked constraints; identify risks/trade-offs; demand justification on contradiction or risk acceptance; record only with explicit operator rationale. - Confidence explicit (LOW / MEDIUM / HIGH). Under LOW: do not lock decomposition, do not move to next phase. - No repeat questions: return only on new conflict or newly-introduced dependency. - Context budget: long dialogues — top-3 questions; Working State as delta; compact Phase Progress; do not repeat full inventory if 1–2 entities changed. All entity inventories, contracts, file structures, decision-log entries baked into Markdown spec files. `task-scaffolding` starts in fresh session without modeling history. **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: - Module spec body text (Module Vision, entity Purpose, contract DbC pre / post / invariant content, Decision Log `Why` / `Risk`). - Halt messages emitted to the operator. - Phase Progress free-text fields. English regardless of context: code, JSDoc, file paths, type / entity / method names, axiom IDs (`AX_*`), Trace anchors, IDs (`D-NNN` / `H_*`), severity / status tokens, structural section headings, field labels (`**Status:**`, `**Why:**`, `**Type:**`, `**Runtime Backing:**`). Final hierarchy contains: - per-module spec 10 Handoff: implementation/test files Scaffolder will create; explicit stack dependencies (language, test framework) Scaffolder resolves against `ai/directives/coding/*`, `ai/directives/testing/*`; **Module Rules Additions** layered on scope-wide baseline. - Modules layer rules ADD-only (cannot remove scope-wide). Categories: `coding` | `testing` | `architecture` | `quality`. No additions → block is explicitly `None`, not omitted. Cascade union (traversed-scopes ∪ target-scope ∪ module ∪ task) is computed by Scaffolder per-task. | 🛑 ID | Trigger | |---|---| | `H_INVALID_SCOPE_TYPE` | scope-type = infrastructure or contracts — module-decomposition is not applicable | | `H_SCOPE_SPEC_MISSING` | `specs//.spec.md` does not exist — run `discovery` first | | `H_INCOMPLETE_SCOPE_SPEC` | Scope spec missing required sections (Vision, Architecture, Golden DX) | | `H_AMBIGUOUS_MODE` | Module specs exist + verb absent + no Pivot Invalidation List | | `H_LOW_CONFIDENCE` | Confidence LOW at decomposition lock or final hierarchy | | `H_INVENTORY_NOT_APPROVED` | Attempted STEP_3 without all-module inventories approved | | `H_REFINE_BREAKING_CHANGE_NO_LOG` | `refine-module` removes public entity / weakens postcondition without Decision Log entry | | `H_OPERATOR_REJECT` | Operator refuses decomposition, inventory, surface, contract, structure, or final hierarchy | | `H_MISSING_RULE_FILE` | Module rule reference does not resolve to existing file (and not `deferred`) | Reference fragment of `specs/backend/payments/payments.spec.md` showing one assembled Port + Adapter pair with Inventory, Surfaces, DbC, Inter-Module Dependencies. Composition reference; individual Output_Contracts describe parts. ```markdown ## 2. Module Usage Example ```ts import { StripePaymentAdapter } from '@/payments'; const gateway = new StripePaymentAdapter({ apiKey: env.STRIPE_KEY }); const txId = await gateway.charge({ orderId: 'ord_42', amount: { value: 1999, currency: 'USD' }, }); // → TransactionId('txn_…') on success // throws InvalidAmountError | UnsupportedCurrencyError | GatewayUnavailableError ``` ## 3. Entity Inventory (Closed-World) _Это полный список сущностей модуля `payments`. Любое введение сущности execution-агентом помимо этого списка считается drift'ом и требует обновления spec._ | Name | Type | Purpose | |------|------|---------| | `PaymentGatewayPort` | Port | Абстракция списания средств. | | `StripePaymentAdapter` | Adapter | Реализация PaymentGatewayPort через Stripe API. | | `PaymentRequest` | Value Object | Намерение списать сумму в валюте по reference order. | | `TransactionId` | Value Object | Идемпотентный идентификатор успешного списания. | ## 4. Entity Surfaces ### `PaymentGatewayPort` - **Type:** Port - **Purpose:** Абстракция списания средств; скрывает детали провайдера от order-флоу. - **Public Operations:** - `charge(request: PaymentRequest) -> TransactionId` — выполнить списание. - `refund(transaction: TransactionId, amount: Money) -> void` — частичный или полный возврат. - **Lifecycle:** singleton, инжектится в OrderProcessor при инициализации. - **Errors & Degradation:** `InvalidAmountError`, `UnsupportedCurrencyError`, `GatewayUnavailableError`. - **Consumers:** Internal `OrderProcessor` (`../../orders/orders.spec.md#orderprocessor`); External — N/A. ## 5. Module Contracts (DbC) #### Port: `PaymentGatewayPort` - **Runtime Backing:** `real-runtime` - **Verification Levels:** `contract`, `integration` - **Deferred Runtime Scope:** None **Contract (DbC):** - Preconditions: - `request.amount > 0`. - `request.currency` входит в supported set из scope spec 4. - `request.orderRef` уникален для каждого вызова `charge` (idempotency). - Postconditions: - При успехе возвращает непустой `TransactionId`. - При неуспехе кидает один из module-errors; баланс не изменён. - Invariants: - Баланс пользователя не уходит в минус без подтверждённого кредитного лимита. - Один и тот же `orderRef` не порождает два transaction'а. #### Adapter: `StripePaymentAdapter` - **Implements:** `PaymentGatewayPort` - **Runtime Backing:** `real-runtime` - **Verification Levels:** `integration`, `e2e` **Side Effects:** - HTTPS-запрос к `api.stripe.com/v1/charges`. - Эмиссия `payment.charged` через ModuleEventBus. ## 9. Inter-Module Dependencies - **Depends on:** `observability` (`../../observability/observability.spec.md`). - **Scope Reference (cross-scope):** `api-contracts` (`../../../api-contracts/api-contracts.spec.md`) — REST API v1. - **Provides to:** `orders` (`../../orders/orders.spec.md`). ``` Validate scope spec; check scope-type; auto-detect mode; open MODULE_MAP or jump to refinement. 1. TRACE_HEADER (STACK `ROOT__INTAKE`). 2. Determine scope name from intake (or ask operator). 3. Read `specs//.spec.md`. Absent → `H_SCOPE_SPEC_MISSING`. 4. Check scope-type in spec: infrastructure or contracts → `H_INVALID_SCOPE_TYPE`. 5. Spec missing required sections (Vision, Architecture/Golden DX) → `H_INCOMPLETE_SCOPE_SPEC`. 6. Apply mode detection table (`AX_MODE_AUTO_DETECT_OR_HALT`). 7. `add-module`: capture target module name from operator. `refine-module`: capture target module(s) from operator or Pivot Invalidation List; skip STEP_1 (decomposition unchanged) — proceed to STEP_2 scoped to named module(s). 8. Briefly reframe: Vision, key architectural decisions from scope spec. Proceed to STEP_1 (or STEP_2 in `refine-module`). Agree on scope decomposition into modules. 1. TRACE_HEADER (STACK `ROOT__MODULE_MAP`). 2. Decomposition Variants (per `AX_MODULE_BOUNDARY_BY_OPERATOR`): 2–3 variants by axis (feature / architectural layer / data ownership / lifecycle). Each: modules with one-sentence Purpose; pros/cons (cohesion, coupling, evolution); hierarchy depth (flat vs nested). 3. Critical Analysis: which variant scales worse, simpler for current team/scope, where artificial-boundary risk lurks. 4. Phase Progress + Approval Check. 5. After choice: Mandatory Rationale Pull («Why this variant? What's critical? What's consciously sacrificed?») → scope spec Decision Log `D-NNN`. STOP. Without approved decomposition + Decision Log entry, transition to STEP_2 forbidden. Closed-world list of all entities for every module. For each module: 1. TRACE_HEADER (STACK `ROOT__MODULE_MAP__EI_`). 2. Entity Inventory Draft: complete list. Each entity = `` + Type + 1-sentence Purpose. 3. Cross-check vs scope spec High-Level Architecture: explicitly list which abstractions found a home. Gaps surfaced explicitly. (Golden DX coverage check — at session close per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP`.) 4. Closed-World Commitment per `AX_CLOSED_WORLD_INVENTORY`. 5. Phase Progress + Approval Check. STOP per module. All inventories must be approved before STEP_3 → otherwise `H_INVENTORY_NOT_APPROVED`. Public surface and consumers for every entity. Module Usage Example per module. Iterate entities (or per-module batches if trivial): 1. TRACE_HEADER (STACK `ROOT__MODULE_MAP__EI__ES__`). 2. Surface Draft per `ENTITY_SURFACE_FORMAT`. 3. Consumers: Internal (file path or entity name), External (CLI/API/Browser/…). No consumer in v1 → mark candidate for removal or `deferred`. 4. ≥1 uncomfortable question per `AX_UNCOMFORTABLE_QUESTIONS`. 5. Phase Progress + Approval Check (per entity or batch). After all surfaces of a module are approved, BEFORE STEP_4 for that module: 6. Draft **Module Usage Example** (section 2 of module spec) — self-sufficient happy-path snippet exercising the public surface drafted in steps 2–3 (init / happy path / минимальный error path). Self-contained; composition with other modules NOT here. Operator approval. STOP. All surfaces + usage examples must be approved before STEP_4. Translate Ports and Adapters into strict DbC contracts. For each module: 1. TRACE_HEADER (STACK `ROOT__MODULE_MAP__DBC_`). 2. Per Port: Preconditions / Postconditions / Invariants. Source = scope spec 4 + entity surface. 3. Per Adapter: `Implements`; Side Effects; `Runtime Backing`; `Verification Levels`; `Deferred Runtime Scope`; Supporting Artifacts. 4. Public Options Audit: every public flag/option/policy from scope spec → bind to contract OR mark `deferred / not consumed in v1`. 5. Critical Analysis: weak runtime backing? silent option drop? Port without confirmed variability (collapse candidate)? 6. Phase Progress + Approval Check (per module). STOP. Design file structure for every module. For each module: 1. TRACE_HEADER (STACK `ROOT__MODULE_MAP__FS_`). 2. Tree Draft: ASCII tree; explicit `ports/` (or `contracts/`) ↔ `adapters/` (or `impl/`) split. 3. File Mapping: which component lives where. ≤1500 lines per file (`AX_MODULARITY_LIMITS`). 4. Namespace Check per `AX_NAMESPACE_NAMING`. 5. Phase Progress + Approval Check (per module). STOP. Generate spec tree; append-only update scope spec 8 Module Map. 1. TRACE_HEADER (STACK `ROOT__FINAL_HIERARCHY`). 2. For each module — `specs///.spec.md` per `MODULE_SPEC_MARKDOWN_STRUCTURE`. - Module spec 1 MUST link back to `../../.spec.md` (parent scope spec). 3. **Scope spec 8 Module Map update (per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP`):** - `initial`: WRITE 8 Module Map with one row per module. - `add-module`: APPEND a row for the new module in 8 Module Map. - `refine-module`: UPDATE the target module's row in 8 Module Map if Purpose changed. Other rows untouched. 4. Rewrite scope-spec Golden DX Example as composition view per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP`. 5. Cross-scope dependencies declared in module spec 9 Inter-Module Dependencies as Scope Reference entries (pointing to contracts-type scope specs), per `AX_CROSS_SCOPE_DEPENDENCIES` in discovery. 6. Run bidirectional consistency check per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP`. Any direction fails → fix and re-run; do NOT proceed to operator review with inconsistency. 7. Output for review. STOP. Push frame on: module boundary challenge; alternative entity or Port proposal; questions about contract/lifecycle/runtime hook/trust boundary; sub-topic that cannot close in one sentence. Pop on: confirmed local conclusion; DEFERRED non-blocking topic; topic requires separate supporting artifact while main flow continues. OPEN | BLOCKED | READY_TO_RETURN | READY_TO_ADVANCE | DEFERRED. On pop: `Return Summary` with Confirmed / Changed / New Constraints / Open / Parent Next. ```text 🧩 DM_R | STACK: ROOT____ | FRAME: F__R | <📂|🚧|↩️|⏭️|💤> | CONF: 🎯 GOAL: ⏭️ EXIT: ``` ```markdown 🎯 Phase Progress — 🧩 Module: (or N/A) ✅ Closed: ⏳ Open: 🛑 Blocking: ▶️ Next: 📊 Counters: ``` ```markdown ### D-NNN — - **Status:** active | superseded | rejected | deferred - **Recorded:** session ModuleDecomposition, - **Why:** - **Risk accepted:** - **Rejected alternatives:** - **Supersedes:** D-NNN (when superseding a prior decision) ``` ```markdown ## Entity Inventory (Closed-World) _Это полный список сущностей модуля. Любое введение сущности execution-агентом помимо этого списка считается drift'ом и требует обновления spec._ | Name | Type | Purpose | |------|------|---------| | `OrderProcessor` | Service | Композитная обработка lifecycle заказа | | `PaymentGatewayPort` | Port | Абстракция для списания средств | | `StripePaymentAdapter` | Adapter | Реализация PaymentGatewayPort через Stripe | ``` ```markdown ### `` - **Type:** Port | Adapter | Entity | Value Object | Service | Command | Query | Event - **Purpose:** <1 sentence> - **Public Properties:** - **Public Operations:** - **Lifecycle:** - **Events Emitted:** - **Errors & Degradation:** - **Consumers:** - Internal: `` or `` - External: ``` ```markdown #### Port: `` - **Purpose:** <1 sentence> - **Consumers:** - Internal: - External: - **Supporting Artifacts:** - **Runtime Backing:** `not-implemented` | `simulation` | `real-runtime` - **Verification Levels:** subset of `contract` | `unit` | `integration` | `e2e` - **Deferred Runtime Scope:** **Contract (DbC):** - Preconditions: - - Postconditions: - - Invariants: - ``` ```markdown #### Adapter: `` - **Implements:** `` (``) - **Purpose:** <1 sentence> - **Supporting Artifacts:** - **Runtime Backing:** `not-implemented` | `simulation` | `real-runtime` - **Verification Levels:** subset of `contract` | `unit` | `integration` | `e2e` - **Deferred Runtime Scope:** **Side Effects:** - ``` Each `specs///.spec.md`. Every top-level `## N.` section wrapped with `…` (open before header, close before next same-level header or EOF). Sub-sections and entity-level headers are NOT wrapped — they live inside the containing anchor. Section names are author-discretionary; the template below shows idiomatic choices. Grammar source of truth: `~/.claude/skills/sdd-execute/scripts/extract-section.sh`. DbC subsection shape is flexible per `AX_PORTS_AND_ABSTRACTIONS_DISCIPLINE`. ```markdown # Module: ## 1. Module Vision [What this module owns. Link to parent scope spec → `../../.spec.md`. Links to parent/child modules if any.] ## 2. Module Usage Example [MANDATORY. Self-sufficient happy-path snippet — как потребитель использует этот модуль в изоляции. Показывает публичную поверхность через реальный сценарий вызова: init / happy path / минимальный error path. Composition с соседними модулями — НЕ здесь, это уровень scope spec (link, не дублировать).] ## 3. Entity Inventory (Closed-World) [Per `ENTITY_INVENTORY_FORMAT`.] ## 4. Entity Surfaces [Each entity per `ENTITY_SURFACE_FORMAT`.] ## 5. Module Contracts (DbC) ### 5.1 Ports [Per `DBC_PORT_FORMAT`. Omit if this module has no Ports.] ### 5.2 Adapters [Per `DBC_ADAPTER_FORMAT`. Omit if this module has no Adapters.] ## 6. Public Options & Policies [All publicly observable flags/options/policies, either bound to contracts above OR explicitly `deferred / not consumed in v1` with link to ticket/version that activates them.] ## 7. File Structure ``` / ├── ports/ │ └── -. ├── adapters/ │ └── --. └── ... ``` **File Mapping:** - ``: ## 8. Module Decision Log [D-NNN entries at module level per `DECISION_LOG_ENTRY_FORMAT`. Cross-module or cross-scope → scope spec or contracts spec.] ## 9. Inter-Module Dependencies - **Depends on:** - **Scope Reference (cross-scope):** - **Provides to:** ```mermaid graph TD --> --> -. Scope Reference .-> --> ``` ## 10. Handoff to task-scaffolding - **Implementation files to be created:** - **Test files to be created:** - **Stack dependencies:** - Language: `` (resolves to `ai/directives/coding/-rules.xml`) - Test framework: `` (resolves to `ai/directives/testing/.xml`) - **Module Rules Additions:** (additions on top of scope-wide baseline; `None` if no module-specific rules) | Rule | Category | Source | |------|----------|--------| | | coding \| testing \| architecture \| quality | `ai/directives//.xml` | - **Open risks & validation needs:** ## 11. Implementation Insights [Library wrap patterns, transaction subtleties, fake-runtime pitfalls, etc. Authored after audit-cycle compaction; immutable contract for future readers.] ``` **Module Map (`## 8.`) — append-only.** Golden DX Example (`## 2.` library / `## 3.` product) is rewritten as composition view per `AX_SCOPE_SPEC_MODULE_MAP_OWNERSHIP`. All other scope-spec sections stay intact. ```markdown ## 8. Module Map (post-ModuleDecomposition) Spec hierarchy is materialized at `specs//`. Module specs are at `specs///.spec.md`. ### 8.1 Modules - [](.//.spec.md) — - [](.//.spec.md) — ### 8.2 Inter-Module Dependency Map Per-scope module graph. Edge A→B = «module A depends on module B's public surface». Cross-scope edges (to `contracts`-type scopes) shown with `Scope Reference` label. ```mermaid graph TD orders --> payments orders --> observability payments --> observability payments -. Scope Reference .-> api-contracts ``` ### 8.3 Stack Dependencies - Languages: - Test frameworks: ### 8.4 Handoff to task-scaffolding - **Primary input:** `specs//.spec.md` (this file). - **Required directives:** all `ai/directives/coding/-rules.xml` and `ai/directives/testing/.xml` for the listed stack. - **Open risks & validation needs:** ```