Turn the operator's intent for a scope into an approved scope spec at `specs//.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}. **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`. 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. | 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? | `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. 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. 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. 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` `` section: find every rule whose `` match the tool name or its config artefacts. Record matched rule `` 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. 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. 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. 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. Scope-wide rules are declared in spec Rules. Categories with directory mapping: - coding → `ai/directives/coding/.xml` - testing → `ai/directives/testing/.xml` - architecture → `ai/directives/architecture/.xml` - infra → `ai/directives/infra/.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//.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. 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`. Every non-trivial decision → Decision Log entry. Format: D-NNN, Status, Recorded, Why (operator's wording), Risk accepted, Rejected alternatives. IDs are stable. 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`. For product / library scope: the spec carries Handoff with primary input for `module-decomposition`, named abstractions, open risks. 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. 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. 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. 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. 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. 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`). Global: `DSC_R001`, `DSC_R002`, …. Frame: `F_INTENT_R01`, `F_REQ_R01`, `F_DV_R01`, etc. Stack rendered as `ROOT____` in the header. 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. The spec is self-contained. `module-decomposition` and `task-scaffolding` start without history of this conversation. 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`. **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`), `F-NNN` / `D-NNN` / `H_*` IDs, status / scope-type tokens, BDD keywords, field labels (`**Status:**`, `**Why:**`). | 🛑 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_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 | Resolve scope name, scope-type, mode. Read Portal and rule registry for context. 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 ``, ``, ``, and ``. 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//.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. Lock scope-type and outline which sections the spec will carry. 1. Propose scope-type with rationale. 2. Outline the section set per `AX_SCOPE_TYPE_BRANCH`. 3. Approval Check. STOP. Confirmed → STEP_2. Lock the scope's goal and primary constraints. 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. First type-specific step. 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. Second type-specific step. 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. Third type-specific step. 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. Fourth type-specific step (only some types). 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. 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. 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`. Emit the scope spec. 1. Assemble `specs//.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. 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. Pop on: confirmed local conclusion; deferred non-blocking topic; topic requires a separate supporting artifact while main flow continues. OPEN | BLOCKED | READY_TO_RETURN | READY_TO_ADVANCE | DEFERRED. On pop, emit a Return Summary with: Confirmed / Changed / New Constraints / Open / Parent Next. 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. ```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 | |---|---|---|---| | | coding | ai/directives/coding/.xml | infra (D-NNN) | | | infra | ai/directives/infra/.xml | infra (D-NNN) | ``` ```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 | ``` ```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` ``` ```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). ``` ```text 🦾 DSC_R | SCOPE: | TYPE: | MODE: | STACK: ROOT____ | FRAME: F__R | | CONF: 🎯 GOAL: ⏭️ EXIT: ``` Every top-level `## N.` section is wrapped with `…` markers so any agent can pull a single section via `~/.claude/skills/sdd-execute/scripts/sdd extract `. 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 # : Infrastructure Specification ## scope-type infrastructure ## 1. Vision [Что включает dev/ops experience.] ## 2. Tool Stack ### 2.1 Categories Covered [Список категорий + краткое обоснование исключений.] ### 2.2 Tool Choices | Category | Tool | Rationale | |---|---|---| | | | D-NNN | ## 3. Developer Workflow Example [Shell-script: setup, daily flow, commit flow, debug flow.] ## 4. File Structure [ASCII tree + File Mapping.] ## 5. Effective Rules (for cascade) | Rule | Category | Source | |---|---|---| | | coding | infra (D-NNN) | ## 6. Verification Commands **Mandatory for infrastructure scopes.** After tool stack is finalized, record a table: | Command Name | Invocation | | typecheck-command | | | test-command | | | lint-command | | | format-command | | | check-command | | 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. ## 7. Decision Log [D-NNN entries.] ## 8. Scope Dependencies - **Depends on:** None (infrastructure scopes are typically leaves) - **Provides rules to:** [list of product/library scopes that depend on this] ## 9. Bootstrap Requirements | Requirement | Kind | Owner | Resolution | |---|---|---|---| ## 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] ``` ```markdown # : Contracts Specification ## scope-type contracts ## 1. Vision [Что контракт определяет и для кого.] ## 2. Interface Declaration - **Schema format:** OpenAPI 3.x | gRPC proto3 | JSON Schema | GraphQL SDL - **Versioning scheme:** semver | date-based (YYYY-MM-DD) | none - **Namespace:** - **Interfaces:** [список endpoint groups / message types / operations] ## 3. Versioning Policy [Semver rules / breaking-change protocol / deprecation window.] ## 4. Compatibility Matrix | Consumer scope | Min compatible version | Breaking change protocol | |---|---|---| ## 5. Decision Log [D-NNN entries.] ## 6. Scope Dependencies - **Depends on:** [infra scopes if any] - **Provides contracts to:** [product/library scopes] ## 7. Bootstrap Requirements | Requirement | Kind | Owner | Resolution | |---|---|---|---| ## 8. Handoff - **Contract files to scaffold:** [schema files, codegen configs] - **Bootstrap tickets ready for cascade:** see 7 - **Open risks:** [versioning gaps, unconfirmed consumers] ``` ```markdown # : Library Specification ## scope-type library ## 1. Vision & Primary Goal [Что library делает; главная проблема, которую решает.] ## 2. Approved Golden DX Example [Публичный API DX: init/setup + happy path + error path. Комментарии раскрывают намерение.] ## 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 | |---|---|---| ## 4. Public API Surface [Ключевые exported interfaces, types, functions. Intent-level, без impl detail.] ## 5. Architecture [Выбранный design pattern. Кратко — rejected alternatives.] ## 6. Decision Log [D-NNN entries.] ## 7. Scope Dependencies - **Depends on:** [infra-*, contracts scopes] - **Provides to:** [consumer scopes] ## 8. Bootstrap Requirements | Requirement | Kind | Owner | Resolution | |---|---|---|---| ## 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] ``` ```markdown # : Scope Specification ## scope-type product ## 1. Vision & Primary Goal ## 2. Project Type - **Type:** app[mobile|desktop|spa] | service-module-sdk | cli-utility - **Why this type:** [Краткое обоснование.] ## 3. Approved Golden DX Example [Commentary-rich: init/setup + happy path + error/degradation path.] ## 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 | |---|---|---| ## 5. High-Level Architecture [Выбранный вариант. Block diagram. Краткие описания.] ### 5.1 Rejected Alternatives ## 6. Decision Log [D-NNN entries.] ## 7. Scope Dependencies - **Depends on:** [infra-*, api-contracts, design-system-* scopes] - **Provides to:** [consumer scopes, if any] ## 8. Bootstrap Requirements | Requirement | Kind | Owner | Resolution | |---|---|---|---| ## 9. Module Map [Appended by `module-decomposition`. Initially: «Modules not yet decomposed — run `module-decomposition `».] ## 10. Handoff to module-decomposition - **Primary input:** `specs//.spec.md` - **Areas requiring decomposition:** [list] - **Named abstractions:** [from Golden DX] - **Bootstrap tickets ready for cascade:** see 8 - **Open risks:** [validation needs] ``` ```markdown ### D-NNN — - **Status:** active | superseded | rejected | deferred - **Recorded:** session Discovery, - **Why:** - **Risk accepted:** - **Rejected alternatives:** - **Supersedes:** D-NNN (when superseding) ``` 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 — (rework) - **Status:** active - **Recorded:** session Discovery, , pivot - **Supersedes:** D-MMM - **Pre-rework state:** git ref `` (snapshot of spec immediately before this pivot) - **Was:** - **Now:** - **Why:** - **Risk accepted:** - **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`). ```markdown ### 9.1 Pivot Invalidation List - **Module specs requiring refine:** [list with reasons] - **Tasks requiring reopen:** [TSK-NN — reason] - **Rules to revisit:** [list] ```