gennady 0.8.3 → 0.8.4-draft.2

package/ai/kit/axiom/process/ax-permitted-bash-commands.xml

@@ -0,0 +1,31 @@
+<Axiom id="AX_PERMITTED_BASH_COMMANDS">
+      This role's bash commands stay within this list:
+      - **Must run:** `sdd-verify <target-files>` — MANDATORY. Auto-discovers and runs typecheck, gennady DBC lint, linter, tests, and format check for the project. Runs before §5 commands. **RUN-ALL**: every gate executes regardless of previous failures; failures accumulate. **SUPPRESS-ON-SUCCESS**: passing gates produce zero output; only failed gates dump their command, exit code, and captured output. On all-pass: single summary line. Failing gate → fix and re-run before EMIT_HANDOFF. Log each passing gate on a separate `ver` line.
+      - **Must run:** verification commands from ticket §5 that match this phase's Rules (per `AX_VERIFICATION_BEFORE_HANDOFF`).
+      - **May run:** `ls <dir>` for targeted recon (NOT `-la` or recursive); `tsc --noEmit` after code changes; `node --test <specific test file>` for test-kind phases; `date -u +%Y-%m-%dT%H:%M:%SZ` for timestamps.
+      - **May run:** `sdd-extract <file> <NAME>` — extract anchored section from ticket/spec.
+      - **May run:** `gennady lint <file>...` — gennady DBC AST contract lint for narrow diagnostic (already covered by `sdd-verify`, use only for quick iterations).
+
+      Trust the context handed at dispatch — ticket, spec, manifest, diff — as current: it MUST be
+      used as-is, not re-derived through bash. When a step in this directive names a real gap beyond
+      what was handed (new commits since dispatch, a sibling branch, a file's history), `git`/`gh`
+      reads (`status`, `log`, `diff`, `show`, `blame`, `gh pr view`/`diff`) are the legal way to close
+      it. Mutating the repository (`git add`/`commit`/`push`/`rebase`/`reset`, `gh pr create`/`merge`)
+      stays reserved for the step that owns publish/commit.
+
+      Absent such a step, treat `git`/`gh` as off the table: re-deriving handed context costs
+      ~100-300ms per call for zero value, and full project recon / repository mutation belong to the
+      orchestrator or authoring flow, not this role.
+
+      **Forbidden:** `npm run lint` alone (overkill — use `sdd verify` or `tsc --noEmit` for narrower checks); `npm run format`; `prettier` directly; any recursive or project-wide file scan; any command that reads unrelated files for «context».
+
+      **Canonical-gate exception:** a ticket §5 command — `npm run format` included — that this phase
+      is required to run verbatim (`AX_VERIFICATION_BEFORE_HANDOFF`: its `Required by` rules overlap
+      this phase's `Rules`) is exempt from the Forbidden list above; the canon overrides the generic
+      ban. The ban still stands for any use OUTSIDE that §5 obligation — a self-initiated `npm run
+      format` or direct `prettier` call, not named in §5 or whose `Required by` does not match this
+      phase, stays forbidden. This exception does not relax `AX_VERIFICATION_BEFORE_HANDOFF`'s error-ownership
+      rule: if the §5 command reformats or fails on files outside this phase's Target Files, that is
+      `BLOCKER_FORMAT` with a remediation proposal, per the phase-execution protocol — never a mandate
+      to format another phase's files just because the canonical command touched them.
+    </Axiom>

package/ai/kit/axiom/process/ax-phase-scope-lock.xml

@@ -0,0 +1,3 @@
+<Axiom id="AX_PHASE_SCOPE_LOCK">
+Touch only this phase's `Target Files`. Reading other files (specs, sibling-phase code, rule files cited in this phase's Rules list) is allowed and expected. Writing anywhere outside this phase's Target Files → `H_OUT_OF_PHASE_WRITE`. Operator decides via re-planning or new task.
+</Axiom>

package/ai/kit/axiom/process/ax-preflight-blast-radius-scoped.xml

@@ -0,0 +1,10 @@
+<!-- new for sdd-v2: size the FLOW_VERSION/READINESS preflight gate to the task, not the whole repo -->
+<Axiom id="AX_PREFLIGHT_BLAST_RADIUS_SCOPED">
+  The `FLOW_VERSION=v1` / `READINESS=not-ready` preflight gate protects scope-spanning work — a full
+  migration or readiness setup dwarfs a narrow request. Size the gate to the task's own blast radius
+  before firing it: when the requested change stays inside the door's own scope (a spec paragraph, a
+  single ticket) and never touches `tasks/` layout or a missing gate script, record the state in one
+  line and proceed straight to the door's own work — offer migration / readiness setup to the operator
+  as a separate next step, not inside this run. A change whose blast radius does reach `tasks/` layout,
+  task-ID rewriting, or a missing gate script fires the gate as before, ahead of the door's own work.
+</Axiom>

package/ai/kit/axiom/process/ax-problem-probes-spec.xml

@@ -0,0 +1,14 @@
+<!-- new for sdd-v2 reconcile: a problem is a probe into the spec, not a symptom to patch -->
+<Axiom id="AX_PROBLEM_PROBES_SPEC">
+  Any reported problem, bug, or freeform change is first a question about the spec, not a line to patch.
+  Before reconciling, establish three things against the spec:
+  - **Bug or spec-defect?** Does the code violate a correct spec (→ fix the code), or is the code right
+    and the spec was wrong (→ fix the spec and cascade downstream)? This decides which corner of the
+    spec ⟷ code ⟷ task triangle moves.
+  - **The class.** Judging by the spec + this problem, where else does the same class occur? One report
+    is a symptom — scan the closed-world inventory / contracts for siblings (`orient`).
+  - **The blast radius.** From the diff, what else did the change touch that must be re-examined?
+
+  Patch only the symptom and you have not done SDD — the spec mediates everything, so reconcile at the
+  right level and propagate.
+</Axiom>

package/ai/kit/axiom/process/ax-progressive-disclosure.xml

@@ -0,0 +1,8 @@
+<!-- source: sdd-opt-v1 PROGRESSIVE_DISCLOSURE -->
+<Axiom id="AX_PROGRESSIVE_DISCLOSURE" cross-cutting="true">
+  Decision first, reasoning on demand. The must-read top of a message is short: where we are + my
+  read + what to decide. Everything heavy — full option comparison, evidence, the change-list,
+  derivations — goes BELOW a `### ↓ Детали — по желанию` header. Never dump reasoning above the
+  questions. Facts already verified collapse to one line («сверился: …»); uncertainties that need
+  the operator BECOME the questions — never list them twice.
+</Axiom>

package/ai/kit/axiom/process/ax-q-ids.xml

@@ -0,0 +1,3 @@
+<Axiom id="AX_Q_IDS">
+Index questions with `Q_<SEMANTIC_ID>:`. 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`.
+</Axiom>

package/ai/kit/axiom/process/ax-re-dispatch.xml

@@ -0,0 +1 @@
+<Axiom id="AX_RE_DISPATCH">Any edit → re-dispatch mandatory. Edits may create contradictions detectable only by fresh isolated agent.</Axiom>

package/ai/kit/axiom/process/ax-read-per-manifest.xml

@@ -0,0 +1,11 @@
+<!-- new for sdd-v2 tooling lens: bound worker context to the tool's read-manifest -->
+<Axiom id="AX_READ_PER_MANIFEST">
+  When a tool hands a read-manifest for the current step — the exact rule anchors, spec anchors,
+  ticket sections, and Target Files to read — read EXACTLY that, nothing beyond it. The manifest's
+  "do not read" list and line budget are binding.
+
+  - Pull single blocks by anchor (`sdd-extract <file> <ANCHOR>`), not whole files: reading a fat file
+    end-to-end for one section clogs context and degrades a cheaper model on long input.
+  - Need something the manifest does not list? That signals the ticket or manifest is wrong — log a
+    `discovery` line and surface it; never silently widen the read.
+</Axiom>

package/ai/kit/axiom/process/ax-rejection-reason.xml

@@ -0,0 +1 @@
+<Axiom id="AX_REJECTION_REASON">Every rejection cites specific context: file, section, entity that resolves the concern. No vague "more context."</Axiom>

package/ai/kit/axiom/process/ax-reopen-format.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/sdd/fix.directive.xml -->
+<Axiom id="AX_REOPEN_FORMAT">
+      When reopening a task ticket, append to Execution Log:
+
+      ```
+      ### Round N — <YYYY-MM-DD>, fix: <one-line reason>
+
+      | Phase | Kind  | Status | Target Files | Deps |
+      |-------|-------|--------|-------------|------|
+      | P1    | fix   | [ ]    | <paths>     | —    |
+      ```
+
+      Set ticket Meta Status → `[ ] TODO`. Update `Reopens: <new count>`.
+      Sync tracker: `tasks/<scope>/README.md` row → `[ ] TODO`, `tasks/README.md` index → adjust counts.
+    </Axiom>

package/ai/kit/axiom/process/ax-scale-proportional-depth.xml

@@ -0,0 +1,8 @@
+<!-- new for sdd-v2: SCALE axis — the depth invariant shared by router (source) and branches (consumers) -->
+<Axiom id="AX_SCALE_PROPORTIONAL_DEPTH">
+  Process depth is proportional to the declared SCALE: SCALE governs interview depth, the number
+  of design alternatives explored, and the weight of the verification tail. SCALE becomes binding
+  only after operator confirmation — the router proposes a default, the operator confirms or
+  corrects it; a silently self-assessed scale is void. Branches read the confirmed `scale:` from
+  the session file (`SESSION_FILE_FORMAT`) and size their process to it.
+</Axiom>

package/ai/kit/axiom/process/ax-scratch-log.xml

@@ -0,0 +1 @@
+<Axiom id="AX_SCRATCH_LOG">`## Critic Rounds` = temporary working memory for orchestrator between rounds. Deleted on final CLEAN.</Axiom>

package/ai/kit/axiom/process/ax-step-by-step-approval.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/sdd/svelte-ui-discovery.directive.xml -->
+<Axiom id="AX_STEP_BY_STEP_APPROVAL">
+      Многоступенчатый flow. Каждый шаг завершается Approval Check — оператор подтверждает или поправляет. Без подтверждения следующий шаг не начинается.
+
+      Шаги:
+      1. SKELETON — скелет компонента (иерархия, слоты)
+      2. AXES — оси вариативности (size, appearance, mode, state)
+      3. TOKENS — дизайн-токены (маппинг, overrides)
+      4. API — пропсы, события, слоты
+      5. A11Y — доступность
+      6. STORYBOOK — план stories
+      7. FINAL — утверждение спеки
+    </Axiom>

package/ai/kit/axiom/process/ax-stop-no-edits.xml

@@ -0,0 +1 @@
+<Axiom id="AX_STOP_NO_EDITS">Zero edits → stop. Unchanged input → unchanged verdict → infinite loop.</Axiom>

package/ai/kit/axiom/process/ax-surgical.xml

@@ -0,0 +1 @@
+<Axiom id="AX_SURGICAL">Close the gap only. No restructure, rewrite, restyle. Structural overhaul → suggest re-scaffold, stop.</Axiom>

package/ai/kit/axiom/process/ax-task-id-uniqueness.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_TASK_ID_UNIQUENESS">
+  **Task-ID `<ACR>-<slug>` is unique, semantic, and immutable.** The slug names the feature, not a
+  sequence number.
+
+  - Uniqueness is enforced by the **Slug Registry** in each `<module>.3-tasks.md`: the same slug in two
+    branches collides on merge there, surfacing «same feature» instead of hiding it. Append-only.
+  - The ID never changes — even if the ticket file moves between scopes.
+  - Code references via file headers (`@tasks:`) point to IDs, not paths.
+  - `sdd-check` cross-checks integrity; a genuine collision → abort, operator resolves.
+</Axiom>

package/ai/kit/axiom/process/ax-task-parallel.xml

@@ -0,0 +1 @@
+<Axiom id="AX_TASK_PARALLEL">Tasks critiqued in DAG layers. Same layer (no inter-dependencies) → parallel dispatch. Different layers → sequential.</Axiom>

package/ai/kit/axiom/process/ax-task-resolution.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/sdd/fix.directive.xml -->
+<Axiom id="AX_TASK_RESOLUTION">
+  Every fix routes through the task that owns the affected file — ownership is resolved from the
+  artifacts, before classification. `@tasks: <ACR>-<slug>[, ...]` in a file header names the owning
+  task(s). Files matching `*.task.<ACR>-<slug>.md` (co-located under `specs/`) are tickets — the
+  Task-ID is in the filename. Files matching `*.1-spec.md` / `*.spec.md` are spec files — linked to a
+  scope, not a single task. Index files (`*.2-tasks.md` / `*.3-tasks.md`, `specs/2-tasks.md` /
+  `specs/3-tasks.md`) are global artifacts, owned by no task. The resulting file → [Task-IDs] map is
+  what routes fixes per `AX_FIX_CLASSIFICATION`.
+</Axiom>

package/ai/kit/axiom/process/ax-ticket-section-names-normative.xml

@@ -0,0 +1,3 @@
+<Axiom id="AX_TICKET_SECTION_NAMES_NORMATIVE">
+**Section anchor names templated in `TASK_TICKET_STRUCTURE` are normative, NOT illustrative** — the orchestrator (`sdd-execute`) and the auditor query them by exact string. Renaming or omitting a templated anchor breaks programmatic dispatch and traceability.
+</Axiom>

package/ai/kit/axiom/process/ax-tool-invocation.xml

@@ -0,0 +1,12 @@
+<!-- source: sdd-v2 tool-invocation convention -->
+<Axiom id="AX_TOOL_INVOCATION">
+  The SDD mechanical tools are `gennady` CLI commands. When working IN the gennady repo itself
+  (including any of its worktrees), invoke them repo-relative from the working tree's own root —
+  `npx tsx <repo-root>/cli/gennady.ts <cmd> <args>` — never a hardcoded path to a different checkout;
+  this is rewritten to `npx gennady <cmd> <args>` by the path-normalizer when the directives are
+  synced into a project. In every OTHER project, invoke the published package: `npx gennady <cmd>
+  <args>`. Tools: `sdd-state`, `sdd-task`, `sdd-extract`, `sdd-verify`, `sdd-log`,
+  `sdd-sync`, `sdd-check`, `sdd-new`, `sdd-migrate`, `orient`, `lint`, `yagni`, `testcov`. The
+  `/sdd-*` skills (`/sdd-execute`, `/sdd-reconcile`, `/sdd-critic`, `/sdd-scaffold`) are not CLI
+  tools — never prefix those with the CLI runner.
+</Axiom>

package/ai/kit/axiom/process/ax-verification-before-handoff.xml

@@ -0,0 +1,19 @@
+<Axiom id="AX_VERIFICATION_BEFORE_HANDOFF">
+Phase cannot emit Handoff without Verification commands relevant to this phase passing. Each command from ticket §5 Verification whose `Required by` rules overlap with this phase's `Rules` MUST execute **verbatim — exactly as listed in ticket §5**; result + exit code recorded as `<ts> ver <cmd> → pass|fail exit=<N>` where `<cmd>` is the literal string from §5. Any failing command keeps phase `[~] IN_PROGRESS` until resolved or escalated.
+
+**MANDATORY (PROTOCOL) — Canonical Gate Rule:** Ticket §5 commands are CANONICAL and CANNOT be substituted. Running an "equivalent" command (e.g. `npx vitest run` instead of `npm run check`, or `tsc --noEmit` instead of the ticket's `npm run typecheck`) and then logging the §5 command as `ver` is **fabricated verification** — treated by audit as `EXECUTION_LOG_INCOMPLETE` (BLOCKER severity, tag `fabricated-verification`). The log line `ver <cmd>` MUST be the exact string of the command that was actually executed, never a paraphrase.
+
+The canon covers the script's BODY, not just its name in §5. Editing what a §5 script actually runs
+(e.g. rewriting `"typecheck"` in `package.json` so it does less, or points elsewhere) while logging the
+unchanged §5 command name as `ver` is the same violation under the same tag — the command name stayed
+canonical on paper while its behavior was substituted underneath it. The one exception: `package.json`
+(or the script body) is itself among this phase's Target Files AND the change to that script IS the
+phase's stated Objective (a `bootstrap` / `config` phase whose job is exactly to define or rewire the
+script) — then the edit is legitimate work, not a gate dodge, and MUST be recorded as its own decision
+line in the Execution Log (`<ts> decision <script> rewritten ← <reason>`) before the gate is logged as
+passing.
+
+Supplemental tools (`sdd-verify`, `tsc --noEmit`, `npx vitest run <file>`) MAY run additionally for narrower diagnostics, but they NEVER replace ticket §5 commands. If a §5 command requires more time/scope than the supplemental tool, run the §5 command anyway — it is the contract.
+
+Phase kind `doc` typically has no verification — empty section is acceptable.
+</Axiom>

package/ai/kit/axiom/process/ax-verify-and-finalize.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_VERIFY_AND_FINALIZE">
+Finalizing a test = re-checking isolation, naming, anchor pairing, snapshot placement, and the diagnostic quality of failures, then running type-check + tests with coverage. Blocker → declared EXPLICITLY.
+</Axiom>

package/ai/kit/axiom/process/ax-verify-at-end.xml

@@ -0,0 +1,4 @@
+<Axiom id="AX_VERIFY_AT_END">
+After all tasks complete, run sdd-check. All checks must PASS.
+If sdd-check finds issues → classify them as new findings → ask operator → fix cycle repeats.
+</Axiom>

package/ai/kit/axiom/scaffold/ax-append-only-module-add.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_APPEND_ONLY_MODULE_ADD">
+      In `add-module` mode existing module specs are NOT touched. Only:
+      - new `specs/<scope>/<new-module>/<new-module>.spec.md`;
+      - scope spec 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 the `module` flow again in `refine-module` mode for that specific module.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-bootstrap-ticket-derivation.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_BOOTSTRAP_TICKET_DERIVATION">
+      **Bootstrap Requirements rows with Owner=`this-scope-task` aggregate into the minimum number of tickets per `AX_DAG_AND_TICKET_BOUNDARIES`.** Default — group by Resolution affinity (all `package` rows → one «install deps» ticket; all `structural` rows editing the same config file → one ticket); subdivide only when (P) parallel-executable or (C) context overflow. Source: scope spec Bootstrap Requirements (infrastructure 9, contracts 7, library 8, product 8).
+      - Rows with Owner=`external-prereq-scope` → cross-scope dependency edge, not a ticket here.
+      - Rows with Owner=`operator-action` → noted in tracker index as a blocking external prerequisite, not a ticket.
+      - Bootstrap tickets must be DONE before any non-bootstrap ticket of the same scope (e.g. `install package` precedes `wire config that uses package`).
+      - Bootstrap tickets carry Verification populated from the Resolution column (e.g. `npm ls <pkg>` exit 0).
+      - If Bootstrap Requirements is absent from the spec → abort with `H_BOOTSTRAP_REQUIREMENTS_MISSING` (the spec did not pass discovery STEP_7).
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-cross-scope-task-placement.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_CROSS_SCOPE_TASK_PLACEMENT">
+      Cross-scope integration tasks belong to the scope that **initiates or owns** the integration. If both sides have equal weight, create a dedicated `integration` scope in the Scope Graph and register it in `specs/README.md`. Never scatter pieces of one integration across multiple scope folders. `tasks/_integration/` is deprecated — do not create it.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-dag-and-ticket-boundaries.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_DAG_AND_TICKET_BOUNDARIES">
+      **Topological order, no cycles. Default: minimum tickets — one per coherent spec unit.** Product / library scope → one ticket per module-spec. Infrastructure / interface scope → one ticket per discrete capability.
+
+      DAG edges derive from real file-level dependencies, Bootstrap → consumers, and cross-scope `depends-on`. No «logical layer» phases — Ports → Adapters → Integrations is an analysis aid in discovery, NOT a ticket-multiplication rule. A Port and its single confirmed-v1 Adapter co-edit and live in one ticket.
+
+      **Split one ticket into N only when BOTH conditions hold:**
+      - **(P) Parallel sub-process potential** — N phase-subagents dispatched simultaneously; Target Files disjoint across all phases of each ticket; no Deps edge among the N.
+      - **(C) Context budget overflow** — combined cascade Rules + Spec References + Target Files exceed comfortable single-context for one phase-subagent's phase.
+
+      **NOT a reason to split:** audit milestone granularity (audit runs once per ticket regardless of size); logical layering (Port + Adapter ship together); partial shippability (consumer can't pick a half-module); human time-units (hours / days — irrelevant for AI execution bounded by context window).
+
+      Sequential split (A → B with hard Deps) without (C) = pure overhead: B's phase-subagent re-reads what A's already loaded; zero wall-clock gain.
+
+      Cross-scope: scope B DONE before A's tasks consuming B's outputs. Bootstrap tickets DONE before non-bootstrap of the same scope.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-directive-mode.xml

@@ -0,0 +1,6 @@
+<!-- source: sdd/discovery + scaffold + module-decomposition (thin kernel; concrete mode set is directive-specific) -->
+<Axiom id="AX_DIRECTIVE_MODE">
+  Each directive runs in one of several modes, auto-detected from operator intake. Mode controls
+  step branching and which axioms apply. The concrete mode set is directive-specific
+  (e.g. `greenfield` / `refine` / `pivot`; `initial` / `extend-dag`; `initial` / `add-module` / `refine-module`).
+</Axiom>

package/ai/kit/axiom/scaffold/ax-extend-dag-preserves-existing-ids.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_EXTEND_DAG_PRESERVES_EXISTING_IDS">
+      **In `extend-dag`, existing Task-IDs and ticket files are immutable.**
+
+      - New tasks get next sequential `TSK-NN` after max existing.
+      - Existing tickets are NOT regenerated even if upstream specs changed — that is the orchestrator's reopen scenario via `sdd-execute`, not regeneration.
+      - `add-scope` upstream → scaffold only for the new scope.
+      - `add-module` or `refine-module` upstream → scaffold only for the new/changed surface; unchanged-surface tickets untouched.
+      - Per-scope Cascade Table may update; existing tickets keep their old per-phase `Rules:` lists — orchestrator re-derives on reopen if the operator opts in.
+      - DAG edges/IDs preserved; new tasks appended.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-handoff-to-task-scaffolding.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_HANDOFF_TO_TASK_SCAFFOLDING">
+      Final hierarchy contains:
+      - per-module spec 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.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-idempotent-modes.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/sdd/setup.directive.xml -->
+<Axiom id="AX_IDEMPOTENT_MODES">
+  `setup` has no hard modes (no greenfield / extension / pivot).
+  - Portal absent → create from scratch.
+  - Portal present → read and propose updates derived from intake; operator dictates what to change.
+
+  No silent assumptions: empty intake against an existing Portal → HALT `H_NO_INTENT` («what are we changing today?»).
+</Axiom>

package/ai/kit/axiom/scaffold/ax-mode-auto-detect-or-halt.xml

@@ -0,0 +1,6 @@
+<!-- source: sdd/discovery + scaffold + module-decomposition (thin kernel; detection table is directive-specific) -->
+<Axiom id="AX_MODE_AUTO_DETECT_OR_HALT">
+  Mode detection is mechanical and table-driven from intake (artifact presence + operator verb).
+  Ambiguous intake never defaults silently → HALT and ask the operator (binary disambiguation
+  where possible). The detection table is directive-specific.
+</Axiom>

package/ai/kit/axiom/scaffold/ax-phases-declared-in-header.xml

@@ -0,0 +1,20 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_PHASES_DECLARED_IN_HEADER">
+      Every ticket declares its work as an ordered list of phases in `Phases Overview` (compact table) and `Phases` (block per phase). Phase kinds are a closed vocabulary: `bootstrap | impl | test | config | doc | refactor`. (`fix` is reserved for re-runs at execution time, not for scaffolding.)
+
+      One phase = one focused unit of work for one subagent. Cross-phase dependencies (`Deps:`) are explicit. The orchestrator dispatches phases sequentially; the phase-subagent reads ONLY its phase's block, its phase's Rules, and prior-phase Handoff payloads.
+
+      Phase emission rules during scaffolding:
+      - Default mapping per Target Files content:
+        - production source files (e.g. `*.ts`, `*.py` excluding tests) → `impl` phase.
+        - test files (`*.test.*`, `*.spec.*`) → `test` phase, depends on the corresponding `impl`.
+        - third-party tool config files (`eslint.config.*`, `vitest.config.*`, `lefthook.yml`, etc.) → `config` phase.
+        - markdown docs → `doc` phase.
+        - package install + foundational config (from Bootstrap Requirements) → `bootstrap` phase, no Deps.
+        - trivial wiring files (module barrel `index.ts`, parent re-export update, single-line type-alias re-export) → NOT a separate ticket and NOT a separate phase. They are added to the `Target Files` of the `impl` phase that creates the symbols they re-export.
+      - Each phase carries its own `Rules:` list — subset of cascade-derived rules whose `<Triggers>` apply to its file class.
+      - Each phase carries its own `Target Files:` bullet list (NO ticket-level `Target Files` outside phases).
+      - Each phase carries `Inputs:` (`none` or list of prior phase IDs whose Handoff it consumes) and `Exit:` (one-line verifiable criterion).
+
+      Forbidden: emitting a ticket without `Phases Overview` and `Phases`; collapsing impl + test into one phase (they have different rule sets and different verification commands); emitting Target Files at ticket level instead of per-phase.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-rule-activation-plan.xml

@@ -0,0 +1,7 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_RULE_ACTIVATION_PLAN">
+      **Rules activate per phase, not per ticket.** `ai/directives/knowledge.xml` (`<Rules>` section) is the canonical rule registry. Invariants of a correctly activated phase:
+      - A rule is active for a phase exactly when its `<Triggers>` match THAT PHASE's `Target Files` + `kind` AND its `<SkipWhen>` does not apply. Signal-based only — the directive carries zero hardcoded language/tool knowledge.
+      - The phase's `Rules:` bullet list is the **explicit, fully-resolved transitive closure** over `<DependsOn>` — one `[<rule-id>](<rule-file-path>)` per rule, direct + transitive; the phase-subagent reads the list as-is and never walks `<DependsOn>` at runtime.
+      - Every `<RequiresVerification>` alias declared by an active rule resolves through infra-spec Verification Commands into the ticket-level Verification table; the phase-subagent runs only the rows whose Required-by intersects its phase's `Rules`.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-rule-activation.xml

@@ -0,0 +1,8 @@
+<!-- source: sdd/module-decomposition + discovery (converged); trimmed to invariant per AUTHORING.md §7 — the Stage A/B mechanics live in the executing step (scope STEP_7_RULE_ACTIVATION) -->
+<Axiom id="AX_RULE_ACTIVATION">
+  **Every rule activates through an explicit operator decision — never silently.** The decision is
+  two-staged: Stage A locks the relevance shortlist per category with the operator; Stage B walks
+  the axioms of `architecture/*` and `infra/*` rules for Accept (default) / Adapt / Override. Every
+  deviation from a rule default lands in the Decision Log. `coding/*` / `testing/*` rules stay
+  deferred — the phase-subagent loads them at phase entry per `phase-execution-protocol`.
+</Axiom>

package/ai/kit/axiom/scaffold/ax-rules-cascade-resolution.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_RULES_CASCADE_RESOLUTION">
+      **Effective rule-set per task = union of 4 tiers; later tier overrides earlier on collision.**
+
+      Tier order (low → high):
+      1. **traversed-scopes** — union of Effective Rules from all scopes reachable via `depends-on` from target scope (transitive closure).
+      2. **target-scope** — scope spec Effective Rules (infra) or Rules (product/library).
+      3. **module:<name>** — module spec Handoff Module Rules Additions (when modules exist).
+      4. **task** — operator-supplied during ticket generation.
+
+      Invariants of the materialized cascade:
+      - **Cascade Table** (Scope × Categories) lives in `specs/<scope>/<scope>.3-tasks.md` per scope, NOT in `specs/3-tasks.md`.
+      - Rules are declared **per phase only** — a `Rules:` bullet list inside each phase block of the ticket's Phases; a ticket-level rule list is a structure violation.
+      - Auditor recomputes the effective set per-phase from these sources and compares with each phase block.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-rules-load-from-phase-block.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_RULES_LOAD_FROM_PHASE_BLOCK">
+      Open ONLY rule files listed under this phase's `Rules:` bullet list. Use the absolute-or-cwd-relative path verbatim. Read end-to-end (Mission + Belief_State + Reward_Criteria + Anti_Patterns + Verification_Hooks).
+
+      One legal extension: when a cited rule file itself declares a transitive base — an explicit
+      `InheritedBaseline` block, or prose stating "read `<other-file>` first" — that declared base is
+      part of the same rule for scoping purposes and MAY be opened too. It is NOT a discovery: log
+      nothing (no `discovery` line), since the manifest's citation already covers it by way of the
+      rule file's own declaration. This extension is narrow and self-limited by construction — it only
+      ever reaches the base(s) the cited file names, never a sibling phase's rules, never a file the
+      worker decides on its own looks relevant.
+
+      Everything else stays ONLY: rules from sibling phases are NOT this phase's concern, do not
+      pre-load them; a file that looks related but is not cited, and is not a declared base of a cited
+      file, stays unread. Read failure on a cited rule (or its declared base) → `H_RULE_FILE_MISSING`.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-rules-resolution-hard-fail.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_RULES_RESOLUTION_HARD_FAIL">
+      **All rule references must resolve; missing rule = abort.** Sources: scope spec (Effective Rules for infra; Rules for product/library), module spec (Handoff Module Rules Additions), task (operator-supplied at STEP_4). Each ref must exist as `ai/directives/<category>/<rule>.xml`. On miss: abort with explicit list. A placeholder rule reference (TBD, `<rule>`, "to be authored", any unresolved name) = abort, never write a ticket against it.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-scope-rules-declaration.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<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>

package/ai/kit/axiom/scaffold/ax-stack-based-flow.xml

@@ -0,0 +1,6 @@
+<!-- source: sdd/discovery + module-decomposition (thin kernel; concrete main path is directive-specific) -->
+<Axiom id="AX_STACK_BASED_FLOW">
+  The directive runs on an explicit frame stack with a defined main path of phases. Disputes /
+  dives / sub-topics open a nested frame; the stack is visible in the trace header. A sub-topic
+  never silently stalls the parent frame. The concrete main path is directive-specific.
+</Axiom>

package/ai/kit/axiom/scaffold/ax-task-dimensions.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_TASK_DIMENSIONS">
+      Task quality dimensions:
+      1. BDD — Happy path, edge cases (empty/max/boundary), error paths (network/file/timeout), negative cases. Concrete GIVEN/WHEN/THEN required.
+      2. Spec alignment — entity names match spec. Contracts covered by phases. Verification refs correct.
+      3. Phases — ordered correctly, deps explicit, no gaps (impl without test), Target Files non-overlapping.
+      4. Clarity — fresh agent can build from this alone. Inputs/outputs specified.
+      5. Completeness — all sections filled, no <TBD> or <YYYY-MM-DD>.
+      6. Parsimony — task introduces NO entity/type/method absent from the parent spec inventory. New surface declared in a task without spec backing = finding. Spec entities are reused, not re-declared. Cross-project reuse is the orchestrator's check, not yours.
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-ticket-deduplication.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_TICKET_DEDUPLICATION">
+      **Project-wide content lives ONCE in `specs/3-tasks.md`.** Declared there: file-header convention, baseline Completion Rule, Execution Log template, post-task audit hint. Per-scope Cascade Table lives in `specs/<scope>/<scope>.3-tasks.md`. Per ticket: only task-specific Meta, BDD, Test Scenario Coverage, Completion additions (if any), Execution Log instance (initially empty plan).
+    </Axiom>

package/ai/kit/axiom/scaffold/ax-ticket-has-bdd-and-tests.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_TICKET_HAS_BDD_AND_TESTS">
+      **Ticket carries BDD scenarios mapped to concrete tests.**
+
+      - Acceptance Criteria = strict BDD (Given/When/Then) translated from DbC pre/post + Requirements & Constraints + Decision Log. Negative scenarios, fallbacks, trust boundaries, platform limits pulled from spec, not inferred from component name.
+      - Each scenario gets a verification level marker: `contract` | `unit` | `integration` | `e2e`.
+      - Each scenario maps to `<test-file>::<canonical case name>` in Test Scenario Coverage, OR explicit `Deferred Test Ownership: <task-id>`.
+      - At least one phase of kind `test` MUST exist whose Target Files contains the test file, unless every scenario has `Deferred Test Ownership`.
+      - Canonical case names are normative: phase-subagent uses verbatim or updates the ticket before phase DONE.
+      - BDD describes behavior, not language-specific syntax.
+      - For every DbC contract in Spec References (Port / Adapter / Value Object): one `contract`-level typing scenario MUST exist — derived from the textual surface (`AX_CONTRACTS_TEXTUAL_AGNOSTIC`): input/output shape, boundary rejection of invalid values, case exhaustiveness. `Deferred Test Ownership` not allowed for typing scenarios — they ship with the types.
+    </Axiom>

package/ai/kit/axiom/spec/ax-access-patterns-drive-schema.xml

@@ -0,0 +1,7 @@
+<!-- source: sdd-v2 amplify-storage -->
+<Axiom id="AX_ACCESS_PATTERNS_DRIVE_SCHEMA">
+  Schema and indexes derive from named access patterns, in that order: list the queries the
+  product actually runs (read/write mix, cardinality, hot paths) FIRST, then shape tables /
+  collections and indexes to serve them. An index with no named query behind it is dead weight;
+  a hot query with no index plan is a latent incident.
+</Axiom>

package/ai/kit/axiom/spec/ax-context-to-contract.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_CONTEXT_TO_CONTRACT">
+      DbC is derived from context, not only from DX code. Scope spec 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».
+    </Axiom>

package/ai/kit/axiom/spec/ax-contracts-textual-agnostic.xml

@@ -0,0 +1,11 @@
+<!-- reinstates v1 DbC-agnosticism (ex AX_AGNOSTICISM), supersedes AX_CONTRACTS_REAL_LANGUAGE (real-language signatures) per operator decision -->
+<Axiom id="AX_CONTRACTS_TEXTUAL_AGNOSTIC">
+  DbC contracts are textual and language-agnostic. Write preconditions / postconditions /
+  invariants and public operations as plain intent-level statements in the shared vocabulary
+  (Port, Adapter, Entity, Command, Query, Event) — one testable statement per line, readable,
+  free of syntax noise. Concrete signatures and types belong to the execution phase: the coding
+  rules turn the contract into the project's language there. The single exception: Golden DX /
+  usage examples are written in the project's target language — they show consumption, the
+  contract stays textual. A genuinely cross-language contract belongs in an `interface` scope,
+  expressed in its own interface language (schema / proto / IDL), not here.
+</Axiom>

package/ai/kit/axiom/spec/ax-data-lifecycle-explicit.xml

@@ -0,0 +1,7 @@
+<!-- source: sdd-v2 amplify-storage -->
+<Axiom id="AX_DATA_LIFECYCLE_EXPLICIT">
+  Stored data has a declared lifecycle: how it arrives, how it migrates when the schema evolves
+  (expand → backfill → contract; each step reversible), and when it leaves (retention period,
+  deletion mechanics, legal holds). A spec that adds persistence states all three; «храним вечно»
+  is a decision to record, not a default to inherit silently.
+</Axiom>

package/ai/kit/axiom/spec/ax-decision-log-required.xml

@@ -0,0 +1,7 @@
+<!-- source: sdd/discovery + scaffold + module-decomposition (converged to principle) -->
+<Axiom id="AX_DECISION_LOG_REQUIRED">
+  Every non-trivial decision → a Decision Log entry in `DECISION_LOG_ENTRY_FORMAT`
+  (D-NNN, Status, Recorded, Why in the operator's wording, Risk accepted, Rejected
+  alternatives; IDs are stable). Which decisions qualify and which Decision Log receives
+  the entry are specified per directive.
+</Axiom>

package/ai/kit/axiom/spec/ax-draft-ready-for-review.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/coding/uikit-spec-drafting.xml -->
+<Axiom id="AX_DRAFT_READY_FOR_REVIEW">
+      The output is a DRAFT — marked with a header comment:
+      ```markdown
+      &lt;!-- DRAFT: generated from figma-utils extract. Review and finalise before scaffold. --&gt;
+      ```
+      This signals to the operator that the spec is machine-generated and requires human approval.
+</Axiom>

package/ai/kit/axiom/spec/ax-dx-first.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<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 consumer-driven baseline for downstream design; without it, Design Variants accumulate accidental complexity (over-engineering, speculative surface).
+
+      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>

package/ai/kit/axiom/spec/ax-exact-scope.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_EXACT_SCOPE">
+Deliver exactly what the task and contract demand. No unrequested features, extension points, or optionality. Every extra API surface is a future refactor obligation and a source of drift from the contract.
+</Axiom>

package/ai/kit/axiom/spec/ax-external-input-untrusted.xml

@@ -0,0 +1,7 @@
+<!-- source: sdd-v2 amplify-security -->
+<Axiom id="AX_EXTERNAL_INPUT_UNTRUSTED">
+  Every input crossing a trust boundary into the system — user input, webhook, file upload,
+  inter-service call, queue message — is untrusted until validated at that boundary. Validation
+  lives at the boundary itself; inner layers receive already-typed, already-checked data. A spec
+  that names a trust boundary MUST name the validation applied at it.
+</Axiom>

package/ai/kit/axiom/spec/ax-handoff-to-module-decomposition.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_HANDOFF_TO_MODULE_DECOMPOSITION">
+      For product / library scope: the spec carries Handoff with primary input for the `module` flow, named abstractions, open risks.
+    </Axiom>

package/ai/kit/axiom/spec/ax-hierarchical-specs.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_HIERARCHICAL_SPECS">
+      Hierarchy, not flat list. Sub-modules → nested structure: `specs/<scope>/<module>/<sub-module>/<sub-module>.spec.md`. Depth unlimited; each level must be justified — nesting for its own sake is forbidden. All specs are cross-linked.
+
+      Growth is the decomposition trigger: a module that outgrows its cohesion splits into sub-modules and becomes a thin index over them, as a scope indexes its modules (`AX_SCOPE_STAYS_THIN`). The size limit is held by tooling, not prose — `sdd-check` flags an over-budget module spec and the `module` flow offers the operator decomposition (split the world) or compression (tighten the spec).
+
+      Held by tooling: `sdd-check` flags a decomposed module missing from its parent's links (`SDD_MODULE_NOT_IN_INDEX`).
+    </Axiom>

package/ai/kit/axiom/spec/ax-interface-flow.xml

@@ -0,0 +1,7 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_INTERFACE_FLOW">
+      For scope-type=interface:
+      - 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 interface scope.
+    </Axiom>