gennady 0.8.3 → 0.8.4-draft.2

package/dist/ai/kit/axiom/audit/ax-rules-compliance-against-activated-rules.xml

@@ -0,0 +1,22 @@
+<!-- source: ai/directives/sdd/audit.directive.xml -->
+<Axiom id="AX_RULES_COMPLIANCE_AGAINST_ACTIVATED_RULES">
+      Compliance is checked against the union of rules listed across all phases of the Round (per each phase block's `<ts> rules <rule-ids>` line — or equivalently the `Rules:` bullet list in section 3 Phases). Not the full cascade — only what phases actually loaded.
+
+      **Audit is universal — no embedded knowledge of any language, runtime, or tool.** Every rule file exposes the same checkable surface; audit walks these sections mechanically:
+      - `<DependsOn>` → list of rule-file paths this rule architecturally extends (optional; empty for standalone rules). Used by scaffolder for transitive closure, by audit for cascade verification — NOT walked at runtime.
+      - `<BeliefState>` → `<Axiom AX_*>` constraints
+      - `<AntiPatterns>` → `<Bad>` shapes that must not appear
+      - `<VerificationHooks>` → executable check commands
+      - `<RewardCriteria>` → ✅ invariants / ❌ forbidden states
+
+      Required sections: `<BeliefState>` / `<AntiPatterns>` / `<VerificationHooks>` / `<RewardCriteria>`. Optional: `<DependsOn>` (only when the rule extends another). Required section missing → `RULE_FILE_INCOMPLETE` (`MAJOR`); audit proceeds with available sections.
+
+      **Per (artifact ∈ Round diff, rule ∈ union of all phases' Rules):**
+      1. Apply rule's `<Triggers>` / `<ActivationHint>` from `knowledge.xml` to decide if the rule governs this artifact. No match → skip pair.
+      2. Walk Reward_Criteria, Anti_Patterns, Verification_Hooks, then residual axioms (those not covered by the prior three). Each violation → `RULES_COMPLIANCE_VIOLATION` citing the specific ID (`AX_*` / `AP_*` / `HOOK_*` / Reward_Criteria line verbatim) + `Location: <path>:<line>`.
+      3. Decision Log overrides take precedence — adapted / overridden axiom → suppress finding, record `Override-honored: <D-NNN>`.
+
+      **Improper-skip.** Diff has artifact of a category while Execution Log shows `skip` for that category → `RULES_COMPLIANCE_VIOLATION` tagged `improper-skip` (`MAJOR`).
+
+      **No invented criteria.** Suspicion without a backing rule line → `INSIGHT_BACKFLOW` (proposal to add a rule), not a finding.
+    </Axiom>

package/dist/ai/kit/axiom/audit/ax-runtime-backing-verification.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/sdd/audit.directive.xml -->
+<Axiom id="AX_RUNTIME_BACKING_VERIFICATION">
+      Runtime Backing and Verification Levels must match reality.
+      - Ticket declared `real-runtime` → look for real runtime hooks (event listeners, lifecycle subscribers, OS bridge calls). Only manual publish / test seams → `RUNTIME_BACKING_VIOLATION`.
+      - `simulation` allowed only with explicit `Deferred Runtime Scope` either in ticket or in updated spec.
+      - `not-implemented` implies real implementation is still ahead (separate task); confirm only contract artifacts exist; no production logic snuck in.
+      - For each declared `Verification Level`, corresponding test artifact must exist. Mismatch → `RUNTIME_BACKING_VIOLATION`.
+    </Axiom>

package/dist/ai/kit/axiom/audit/ax-severity-tagging.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/sdd/audit.directive.xml -->
+<Axiom id="AX_SEVERITY_TAGGING">
+      Every finding carries a severity:
+
+      | Severity | Meaning |
+      |---|---|
+      | `BLOCKER` | task cannot be considered complete; merge forbidden |
+      | `MAJOR` | protocol violation; requires fix; allows merge only with explicit operator acceptance + Decision Log entry |
+      | `MINOR` | stylistic or secondary discrepancy |
+      | `INFO` | observation without mandatory action (often `INSIGHT_BACKFLOW`) |
+
+      Severity does not depend on agent's mood. Closed-world drift = `BLOCKER` by default; coding-rules violation = `MAJOR`; stylistic deviation = `MINOR`.
+    </Axiom>

package/dist/ai/kit/axiom/audit/ax-severity.xml

@@ -0,0 +1,7 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_SEVERITY">
+      CRITICAL — unusable, downstream agent produces wrong work.
+      MAJOR — gap requiring rework.
+      MINOR — improvement, vague wording.
+      INFO — observation.
+    </Axiom>

package/dist/ai/kit/axiom/audit/ax-stale-after-pivot-verification.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/sdd/audit.directive.xml -->
+<Axiom id="AX_STALE_AFTER_PIVOT_VERIFICATION">
+      When a scope or module spec contains a Pivot Invalidation List, audit verifies every listed artifact has been addressed (scope `pivot` lists it in the scope spec; a breaking `refine-module` lists consumer modules in the module spec — same format, same check).
+
+      | Listed item | Check | Severity if stale |
+      |---|---|---|
+      | Module spec requiring `refine-module` | most recent Decision Log entry references the pivot D-NNN | `MAJOR` |
+      | Task requiring reopen | Reopens counter incremented since pivot date | `MAJOR` |
+      | Rule to revisit | rule file mtime > pivot date | `MINOR` |
+
+      Epic-mode audit aggregates stale items into one summary finding. Greenfield/extension scopes without Pivot Invalidation List → check skipped silently.
+    </Axiom>

package/dist/ai/kit/axiom/audit/ax-task-id-integrity.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/sdd/audit.directive.xml -->
+<Axiom id="AX_TASK_ID_INTEGRITY">
+      File-header task traceability must be structurally valid; Task-IDs in code must resolve; ticket files must not collide on IDs; ticket section anchors must cover the names orchestrator queries.
+
+      Checks:
+      - New or header-carrying files in scope: `@file:` present (`MAJOR` if absent); `@consumers:` present (`MINOR` if absent); `@tasks:` present and contains current Task-ID (`MAJOR` if absent).
+      - `@consumers:` naming convention: value must be an entity name resolvable in the spec or codebase. File paths or directory names → `MINOR`.
+      - Collect all `@tasks: TSK-NN[, TSK-MM, …]` references from in-scope files.
+      - Each ID has a corresponding `tasks/**/*.task-NN.md`. Orphan → `TASK_ID_DRIFT` (`MAJOR`).
+      - Two ticket files declaring same Task-ID → `TASK_ID_DRIFT` (`BLOCKER`).
+      - Compare current `@tasks:` field values against pre-task git ref. Prior IDs removed → `TASK_ID_DRIFT` (`MAJOR`).
+      - **Ticket section-anchor coverage** (per scaffold `AX_TICKET_SECTION_NAMES_NORMATIVE`). For each anchor name templated in `TASK_TICKET_STRUCTURE` invoke `~/.claude/skills/sdd-execute/scripts/sdd extract <ticket> <NAME>`. Exit `2` (ANCHOR_NOT_FOUND/EMPTY) → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged `missing-section-anchor`. Exit `3` (UNBALANCED/DUPLICATED) → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged `anchor-unbalanced`. Optional names (`AUDIT_ROUNDS`, `PIVOT_INVALIDATION_LIST`) — not flagged when absent. Ticket with ZERO required anchors found → escalate to `BLOCKER` (dispatch impossible). Spec section names are author-discretionary → balance is checked by the STEP_1 mechanical pre-pass; no per-name coverage is enforced on specs.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-bootstrap-narrow-read.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_BOOTSTRAP_NARROW_READ">
+      Discovery is design-blind to repository code (per `AX_SPEC_IS_SOLE_SOURCE`) **except** inside STEP_7 (External Dependencies Audit), where narrow Read is permitted **only for inventory verification** — confirming whether a referenced package, file, scope, or tool physically exists.
+      Permitted reads in STEP_7: `package.json` and equivalents, `tsconfig.json` and equivalents, `specs/README.md`, sibling scope manifests, filesystem existence checks.
+      Forbidden in STEP_7: reading application source code to influence design decisions; revisiting Vision / Requirements / Architecture / Contracts based on what was found. If a finding genuinely invalidates a design decision, pop back to the relevant STEP_3–STEP_6 explicitly and treat as `pivot`.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-closed-world-inventory.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_CLOSED_WORLD_INVENTORY">
+      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`.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-cross-scope-dependencies.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_CROSS_SCOPE_DEPENDENCIES">
+      Scope spec declares `depends-on` edges in Scope Dependencies. These edges feed cascade computation in the `scaffold` flow. Cross-scope contracts are sourced from `interface`-type scopes — never described inside a product scope spec.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-entity-surface-completeness.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_ENTITY_SURFACE_COMPLETENESS">
+      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.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-guarded-result-boundary.xml

@@ -0,0 +1,5 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_GUARDED_RESULT_BOUNDARY">
+      A public Result-returning surface guards thrown errors. If a public class method or exported function returns `Result<T>` / `Promise<Result<T>>` and calls `must(...)`, that call must sit inside a try/catch whose `catch` returns `fail(...)` — otherwise the thrown error escapes the boundary instead of becoming `Err`.
+      Detection: explicit return-type annotation `Result`/`Promise<Result>` + a `must` call outside try (no autofix; optional suggestion). ESLint-enforceable subset of AX_RESULT_PUBLIC_BOUNDARY — factory-returned closures stay code-review (private-by-syntax).
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-isolation-signal.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic.directive.xml -->
+<Axiom id="AX_ISOLATION_SIGNAL">Critic receives ONLY artifact + parent spec. Confusion = underspecification. Fix the artifact.</Axiom>

package/dist/ai/kit/axiom/boundary/ax-isolation-through-public-boundary.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/common.xml -->
+<Axiom id="AX_ISOLATION_THROUGH_PUBLIC_BOUNDARY">
+Isolate the SUT by stubbing its external dependencies and exercising it through its public surface. Determinism comes from controlling inputs at the boundary, not from reaching past the boundary to set internal state.
+</Axiom>

package/dist/ai/kit/axiom/boundary/ax-portal-read-only-with-placeholder-exception.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/discovery.directive.xml -->
+<Axiom id="AX_PORTAL_READ_ONLY_WITH_PLACEHOLDER_EXCEPTION">
+  The `scope` flow reads `specs/README.md` for project context (vision, scope graph, sibling scopes). It MUST NOT rewrite the file. The narrow exception (per the `root` flow's `AX_PORTAL_PRIMARY_OWNER`): when the `scope` flow creates a brand-new scope, it MAY append one placeholder row to the Scopes table tagged `🚧 (awaiting root sync)`. Any other edit is forbidden — run the `root` flow instead.
+</Axiom>

package/dist/ai/kit/axiom/boundary/ax-reference-over-copy.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dbc-audit.directive.xml -->
+<Axiom id="AX_REFERENCE_OVER_COPY">The directive coordinates the audit process; it does NOT duplicate the normative body of source artifacts. Findings cite rule references, not re-host the standard.</Axiom>

package/dist/ai/kit/axiom/boundary/ax-result-public-boundary.xml

@@ -0,0 +1,11 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_RESULT_PUBLIC_BOUNDARY" enforcement="convention">
+      Result is the transport form of error across the public / port boundary — not an internal control-flow primitive. Public surface (port interface methods, exported factory return types, closures returned from factories) MUST return `Result<T>`. Inside the same class:
+      - protected/private async helpers with I/O → throw; the public caller wraps in try/catch and returns `fail(error)` (per AX_CATCH_LOG_RECOVER in typescript-rules).
+      - pure helpers (predicates, classifiers) → honest return type (`Error | null`, scalar, enum literal); not Result.
+      - Result in protected is permitted only when the helper carries a typed `kind` the public call-site immediately extracts (via `must`) — and even then, throw is usually cleaner because it avoids the `Result → must → throw → catch → re-emit` double-packaging pattern.
+
+      Rationale: mixing Result and null-pattern in helpers of one class produces structural noise (two error-channel styles in one surface) and double-packaging. The convention keeps Result as a boundary artifact, not an internal one.
+
+      Not ESLint-enforced. The public/private boundary is not mechanically detectable: closures returned from factories (e.g. `defineDataStorageQuery → (storage, params) => Promise<Result<R>>`) are public-by-intent but private-by-syntax, and methods on factory-returned object literals (e.g. `defineDataOperation`) are not visible as class members. Enforced via code review and this directive.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-scope-type-gate.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_SCOPE_TYPE_GATE">
+      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=interface → `H_INVALID_SCOPE_TYPE` (interface scopes define interfaces, not modules).
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-semantic-location-over-lines.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/dbc-audit.directive.xml -->
+<Axiom id="AX_SEMANTIC_LOCATION_OVER_LINES">Findings use stable semantic locations (declaration name, JSDoc block, anchor, method, branch). Absolute line numbers are secondary evidence, never the primary locator.</Axiom>

package/dist/ai/kit/axiom/boundary/ax-semantic-safety.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/perf-auditor/perf-auditor.directive.xml -->
+<Axiom id="AX_SEMANTIC_SAFETY">Если применение правила может изменить поведение (порядок элементов, обработка ошибок, мутабельность) и не можешь доказать обратное → отклони как False Positive.</Axiom>

package/dist/ai/kit/axiom/boundary/ax-spec-never-edited.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_SPEC_NEVER_EDITED">
+      Phase agent does NOT modify `specs/**`. Spec wrong / incomplete / stale → record `<ts> insight <observation> → <spec-section>, <what-change>`. Audit picks up these entries and proposes the spec change; operator approves and applies.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-ssot-traceability.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_SSOT_TRACEABILITY">
+      **The spec is the single source for contract content; a ticket carries references, never copies.** Contract text duplicated into a ticket drifts silently from its source and breaks traceability.
+    </Axiom>

package/dist/ai/kit/axiom/boundary/ax-ticket-write-scope.xml

@@ -0,0 +1,9 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_TICKET_WRITE_SCOPE">
+      Phase agent may edit ticket file ONLY in:
+      - this phase's block under `Execution Log` current Round;
+      - `Test Scenario Coverage` canonical case names (when test reality differs, phase kind = `test`);
+      - `Phases Overview` Status column for THIS phase ID only.
+
+      Anything else (Phases definitions, Rules lists, Target Files, BDD scenarios, Verification table, Dependencies, Meta) → `H_OUT_OF_PHASE_WRITE`. Operator decides via re-planning.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-ai-readability.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/perf-auditor/rules/iteration-fusion.xml -->
+<Axiom id="AX_AI_READABILITY">Человеческая привычка писать "декларативные цепочки" (chaining) не имеет ценности для ИИ. Однопроходный императивный `for...of` с условиями работает быстрее и потребляет меньше памяти.</Axiom>

package/dist/ai/kit/axiom/coding/ax-anchor-format.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_ANCHOR_FORMAT">
+Anchors: `// #region START_[CONTEXT]_[INTENT]` / `// #endregion END_[CONTEXT]_[INTENT]`. Uppercase tokens. Parity mandatory: every `START_X` must have `END_X` in the same file. START_/END_ on top of `#region`/`#endregion` is intentional — paired uppercase tokens are attention anchors for sliding-window LLMs and XML-like span delimiters for long-context retrieval.
+
+When a block has a non-obvious invariant or failure boundary, attach payload inside the anchor (outside it is detached from the block it protects): ONE payload kind → inline on the opening line `// #region START_[NAME] — <key>: <value>`; 2+ kinds → separate comment lines immediately after the opening anchor. Greppable: `#(region|endregion)\s+(START|END)_[A-Z0-9_]+`.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-comment-density.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_COMMENT_DENSITY">
+Comment iff removing it would hide a business rule, invariant, integration constraint, or refactor hazard. Pure data reshaping, obvious getters/setters, trivial guard clauses, straight-line pure computations are NOT commented — silence signals «no hidden policy here». A comment on trivial code falsely tells the agent to look for an invariant that does not exist; a missing comment on non-trivial code forces reverse-engineering.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-comment-placement.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_COMMENT_PLACEMENT">
+Function body starts with executable code. Hidden constraints belong in JSDoc (`@invariant`, `@sideEffect`, `@throws`, `@pre`, `@post`); block-level invariants inside `// #region START_<NAME>` anchors. No narrative brief or rule-summary at method head — JSDoc + signature is the canonical contract surface.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-comment-vocabulary.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_COMMENT_VOCABULARY">
+Closed payload vocabulary: one or more of `purpose`, `consumer`, `invariant`, `side effect`, `failure mode`, `non-goal`. Use terse high-signal prose or `key: value` lines. Closed vocabulary makes comments greppable and predictable.
+
+Forbidden: decorative prefixes (`// NOTE:`, `// IMPORTANT:`) — no machine semantics; narrating loops, branches, assignments, obvious names — steals credit from real policy comments; duplicating JSDoc, types, signatures, log messages. NEVER write «temporary workaround» without (a) the cause, (b) the boundary of applicability, (c) what must remain unchanged — workaround without context is a mine for the next refactor.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-comments-add-nonsyntactic-intent.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_COMMENTS_ADD_NONSYNTACTIC_INTENT">
+All comments are agent-authored machine comments and MUST add intent that an agent cannot safely infer from syntax. A comment SUPPLEMENTS pretrained code understanding instead of fighting it: prefer the smallest local comment that increases recoverable intent / patch safety / invariant preservation. The next reader-agent has no access to the chat in which the code was written — a comment is the only context channel that does not derive from syntax. Excess comments compete with code and drift; insufficient comments force reconstruction from stack traces. Comments do NOT explain syntax to humans; in an AI-to-AI ecosystem, human narrative is noise.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-configurable-names.xml

@@ -0,0 +1,5 @@
+<!-- source: ai/directives/coding/result-conventions.xml -->
+<Axiom id="AX_CONFIGURABLE_NAMES">
+      Every rule that matches function or type names accepts an options object with configurable identifiers: resultTypeName, isErrFn, isOkFn, successFn, failFn, castFn.
+      Defaults match @tessell/core/result exports. On package rename — update config, not the rule.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-consumer-driven.xml

@@ -0,0 +1,8 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_CONSUMER_DRIVEN">
+      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`.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-contractual-naming.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_CONTRACTUAL_NAMING">
+Method name is a self-contained contract. Method names must be readable as a full contract outside the owner class (`verifyRegistrationData`, not just `validate` inside `UserValidator`). A reading agent often sees a method call without the owner class in focus (import, traceability grep). The name must carry meaning in isolation.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-domain-prefix-for-external.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_DOMAIN_PREFIX_FOR_EXTERNAL">
+Domain prefix for types from external systems: `ApiResource`, `VendorOrder`, `ErpCatalogItem`. Internal utilities have no prefix. The prefix protects a trust boundary: `OrderItem` (internal) and `VendorOrderItem` (external) are different entities; conflating is a common source of domain bugs.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-early-exit.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/perf-auditor/rules/iteration-fusion.xml -->
+<Axiom id="AX_EARLY_EXIT">Сканирование 100% массива, когда для ответа достаточно найти один элемент — это растрата процессорного времени. Ранний выход всегда предпочтительнее полного прохода.</Axiom>

package/dist/ai/kit/axiom/coding/ax-explicit-class-fields.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_EXPLICIT_CLASS_FIELDS">
+Declare class fields explicitly in the class body. Put `readonly` on the field declaration, not on constructor parameters. Separates state declaration (what the class holds) from initialization signature (how the class is constructed), removes parameter-property magic, improves introspectability.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-file-header-append-only.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_FILE_HEADER_APPEND_ONLY">
+      Touching a file → ensure file-level header satisfies the execution contract; append your Task-ID to `@tasks`; never remove existing IDs.
+
+      - Required fields: `@file:`, `@consumers:`, `@tasks:`.
+      - New file: create header with all three; populate from ticket context. `@consumers:` derives from spec, never a file path.
+      - Existing file with header: preserve `@file:` and `@consumers:`; append Task-ID to `@tasks:`.
+      - Existing file without header: do NOT add unless this phase explicitly requires header migration.
+      - Re-running same task (e.g., `fix` phase): do NOT add duplicate ID.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-file-header-task-traceability.xml

@@ -0,0 +1,16 @@
+<!-- source: ai/directives/sdd/scaffold.directive.xml -->
+<Axiom id="AX_FILE_HEADER_TASK_TRACEABILITY">
+      **Files carry a unified file-header contract; IDs only, never paths; append-only for `@tasks`.**
+
+      Required file-level fields in execution profile:
+      - `@file` — mandatory; what the file holds.
+      - `@consumers` — mandatory; one or more consumers (see `AX_CONSUMERS_TAG_SEMANTICS`).
+      - `@tasks` — mandatory; associated `TSK-NN` list.
+
+      Canonical header shape:
+      ```
+      // @file: <what the file holds>
+      // @consumers: <consumer-1, consumer-2, ...>
+      // @tasks: TSK-04, TSK-12
+      ```
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-file-level-context.xml

@@ -0,0 +1,13 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_FILE_LEVEL_CONTEXT">
+File-level meta uses line-comments (`// @tag`), never a JSDoc block — distinct syntactic class from entity JSDoc so LLMs and grep distinguish file-scope from entity-scope unambiguously.
+
+Block of consecutive `//` lines at the very top of the file, before any `import`:
+`// @file: <what the file holds>` *(mandatory)*
+`// @consumers: <ConsumerName>` *(optional; omit when no uniform consumer)*
+`// @tasks: <TASK-ID>[, TASK-ID...]` *(optional; may be added later)*
+
+`@purpose` is NOT a file-level tag — it belongs exclusively to entities. Local entities inherit `@consumers` from file level and MUST NOT redeclare it unless their consumer diverges.
+
+`@consumers:` and `@tasks:` are optional — a coding-only agent may lack full project context. Omit rather than fabricate.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-import-canonical-form.xml

@@ -0,0 +1,15 @@
+<!-- source: ai/directives/coding/uikit-component-storybook.xml -->
+<Axiom id="AX_IMPORT_CANONICAL_FORM">
+      Imports in `.stories.ts` follow a fixed order:
+
+      ```typescript
+      import type { Meta, StoryObj } from '@storybook/svelte';
+      import { expect, within } from '@storybook/test';
+      import Button from './button.svelte';
+      ```
+
+      1. Storybook Svelte framework types.
+      2. Storybook test utilities (`expect`, `within`, optionally `userEvent`).
+      3. The component under test (kebab-case import path).
+      4. No other imports unless explicitly required by the story logic.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-introduced-discipline.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/phase-execution-protocol.xml -->
+<Axiom id="AX_INTRODUCED_DISCIPLINE">
+      Every entity introduced beyond the module Entity Inventory MUST be logged: `<ts> intro <EntityName> ← <reason>`. Includes new classes, exported functions, exported types, value objects with explicit identity, anything crossing a public surface. Without an `intro` line, the entity is closed-world drift and audit blocks the task. Mechanically enforced by `InventorySyncCheck` (`gennady lint --spec=<module-spec>`): an exported entity absent from the inventory surfaces as `ERR_CLI_LINT_INVENTORY_UNDECLARED` — resolve by removing it or by backflowing it into the spec inventory (carrying the `intro` reason).
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-modern-ts-density.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_MODERN_TS_DENSITY">
+Modern TS/JS is mandatory. Use optional chaining (`?.`), nullish coalescing (`??`), logical assignment (`||=`, `&&=`, `??=`). Avoid verbose `if`-checks. Semantic density reduces visual noise, shrinks the surface for nullable-check bugs, and makes the code recoverable by an agent in one pass.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-modularity-limits.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_MODULARITY_LIMITS">
+      No God Objects. File size ≤1500 lines. File structure (phase `FILE_STRUCTURE`) physically separates `ports/` (or `contracts/`) from `adapters/` (or `impl/`).
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-namespace-naming.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_NAMESPACE_NAMING">
+      Single namespace for grepability. Module-wide: `<name>` / `<Name>`. Files: `<name>-*.<ext>`. Types/classes/constants: `<Name>*`. Platform-specific: `<platform>-<name>-*.<ext>`, `<Platform><Name>*`. Goal: `rg <name>` or `rg <platform>-<name>` finds all related code.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-no-code-generation.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/perf-auditor/perf-auditor.directive.xml -->
+<Axiom id="AX_NO_CODE_GENERATION">Не пишешь код. Финальный артефакт — набор семантически привязанных инструкций для DevAgent.</Axiom>

package/dist/ai/kit/axiom/coding/ax-no-premature-abstractions.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_NO_PREMATURE_ABSTRACTIONS">
+Forbid premature abstractions. Do not abstract logic that has ONE consumer and ONE concrete realization. Abstraction is justified only by confirmed variance or an explicit second consumer; otherwise it complicates grep and reading without payoff.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-no-silent-escape-hatch.xml

@@ -0,0 +1,4 @@
+<!-- source: SDD v2 — type-safety escape-hatch discipline -->
+<Axiom id="AX_NO_SILENT_ESCAPE_HATCH">
+      A type-system escape hatch — a cast (`as any` / `as unknown` / `as never`, type assertions) or a suppression (`@ts-ignore` / `@ts-expect-error`) — defeats the static guarantees the code relies on. Default: do not use one — model the type properly (narrowing, guards, generics, discriminated unions). When one is genuinely unavoidable it is surfaced and justified in writing, never silent: a documented `@ts-expect-error <reason>` carrying a Decision Log reference (`D-NNN`) that states why it is needed and why the alternatives do not work. A bare cast hides the problem; a documented suppression names it. Enforced mechanically by `CastSafetyCheck` and `DisablesCheck`.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-node-builtins-prefix.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/infra/nodejs-npm-setup.xml -->
+<Axiom id="AX_NODE_BUILTINS_PREFIX">
+  All Node.js built-in module imports use the `node:` prefix.
+
+  `node:` prefix is unambiguous — cannot be shadowed by an npm package with the same name. Also signals intent: «this is a Node built-in, not a third-party dependency».
+
+  Pattern: `import { readFile } from 'node:fs/promises'`, not `from 'fs/promises'`.
+
+  Applies to all built-ins: `fs`, `path`, `http`, `crypto`, `events`, `stream`, `url`, `util`, `os`, `child_process`, `worker_threads`, `perf_hooks`, etc.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-principled-decomposition.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_PRINCIPLED_DECOMPOSITION">
+Decompose by intent, not by volume. Avoid both monolithic methods AND artificial layering. Extract code only at TRUE intent boundaries that meaningfully improve readability, testability, or isolation. Splitting by line count without intent boundaries creates fictive functions that raise cognitive load without raising verifiability.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-teleological-naming.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_TELEOLOGICAL_NAMING">
+A name reflects a goal (teleology), not a pattern (topology). Forbidden semantic-noise names: `Manager`, `Handler`, `Data`, `Info`, `Wrapper`, `do...`, `process...`. Pattern names tell the next agent nothing about business goal. `OrderFulfillmentPipeline` carries intent; `OrderManager` does not.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-tools-as-hands.xml

@@ -0,0 +1,12 @@
+<!-- source: ai/directives/sdd/svelte-ui-discovery.directive.xml -->
+<Axiom id="AX_TOOLS_AS_HANDS">
+      figma-utils — инструментальный слой агента для извлечения SVG-контекста; не источник истины. Агент использует команды для получения данных, но принимает решения самостоятельно на основе полученного контекста:
+
+      - `figma:extract <name>` — полный JSON со всеми вариантами, измерениями, токен-кандидатами
+      - `figma:inspect <name> <pattern>` — точечный зум в конкретный вариант: размеры, элементы, fill/stroke
+      - `figma:tokens find <pattern>` — grep по именам токенов дизайн-системы
+      - `figma:tokens near <value> [delta]` — найти токены, близкие к измеренному значению
+      - `figma:tokens groups` — категории токенов
+
+      Агент НЕ должен полагаться только на extract. Если данные неполны или противоречивы — запустить inspect для конкретных вариантов, найти токены near, перепроверить.
+    </Axiom>

package/dist/ai/kit/axiom/coding/ax-verb-precision.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/coding/typescript-rules.xml -->
+<Axiom id="AX_VERB_PRECISION">
+Use precise verbs. `retrieve` (not `get`), `verify` (not `check`), `compose` (not `make`). Verbs encode the operation's contract. `get` is ambivalent; `retrieve` implies lookup in an external source with possible failure path.
+</Axiom>

package/dist/ai/kit/axiom/coding/ax-yagni-overengineering-guard.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/sdd/module-decomposition.directive.xml -->
+<Axiom id="AX_YAGNI_OVERENGINEERING_GUARD">
+      YAGNI. Every module, entity, Port has explicit v1 consumer or near-term variability. Future-proofing without a confirmed consumer is forbidden.
+    </Axiom>

package/dist/ai/kit/axiom/critic/ax-comprehension-first.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_COMPREHENSION_FIRST">Report understanding before problems. Misunderstanding signals ambiguity.</Axiom>

package/dist/ai/kit/axiom/critic/ax-confusion-bug.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic.directive.xml -->
+<Axiom id="AX_CONFUSION_BUG">Critic confusion ("don't understand X") → artifact underspecified → ALWAYS accept, clarify.</Axiom>

package/dist/ai/kit/axiom/critic/ax-critic-model-tier.xml

@@ -0,0 +1,10 @@
+<!-- source: SDD v2 — S8/S9/S10/S11 flow-sim, operator decision on critic model tier -->
+<Axiom id="AX_CRITIC_MODEL_TIER">
+  The dispatched critic runs on a model no stronger than the artifact's author — default the
+  worker tier (Sonnet-class), never a step up "to be thorough". The consumers of a spec are workers
+  on cheap models; a spec that only a stronger model can parse is not fit for execution
+  (`AX_READER_WITHOUT_SESSION_CONTEXT` carried from prose into tooling). The `understanding` and
+  `implementation-autonomy` lenses ARE the weak model's strength — it surfaces exactly what a
+  worker would trip on. Semantic depth beyond that is not the critic's job; it stays with external
+  review.
+</Axiom>

package/dist/ai/kit/axiom/critic/ax-default-accept.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic.directive.xml -->
+<Axiom id="AX_DEFAULT_ACCEPT">Uncertain → ACCEPT. Cost of rejecting real finding > cost of accepting marginal one.</Axiom>

package/dist/ai/kit/axiom/critic/ax-finding-addressee.xml

@@ -0,0 +1,6 @@
+<!-- source: SDD v2 — question channel: findings routed by who owns the resolution -->
+<Axiom id="AX_FINDING_ADDRESSEE">
+  Every finding carries an addressee — who owns its resolution:
+  - `MECHANICAL` — style, structure, consistency, a detail the spec already implies. Resolved by an artifact edit.
+  - `GOAL` — goal / scope shift ("goal drawn too narrow"), misunderstood intent, a missing requirement, an unanswered uncomfortable question. Resolved ONLY by the goal owner — the operator.
+</Axiom>

package/dist/ai/kit/axiom/critic/ax-goal-owner-gate.xml

@@ -0,0 +1,7 @@
+<!-- source: SDD v2 — critic question channel: GOAL findings need operator sanction -->
+<Axiom id="AX_GOAL_OWNER_GATE">
+  The operator owns the goal. A `GOAL` finding is resolved by an operator answer, and the edit follows
+  the answer — `AX_DEFAULT_ACCEPT` covers `MECHANICAL` findings only. Batch the round's `GOAL` findings
+  into ONE question block (`QUESTION_FORMAT`) BEFORE editing the sections they touch. Goal / scope
+  wording stays intact until an operator answer sanctions the change.
+</Axiom>

package/dist/ai/kit/axiom/critic/ax-isolation.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_ISOLATION">The artifact + its parent spec + the Vision / Goals of its direct NEIGHBOURHOOD — both what it depends on AND its consumers (who depend on it) — pulled via `sdd-extract <dep> VISION` (`MODULE_VISION` for a module), Vision sections only, to understand the system the design serves and who it serves. No other files, no full dependent specs. Confusion → underspecification, not a question to ask.</Axiom>

package/dist/ai/kit/axiom/critic/ax-polish-mode.xml

@@ -0,0 +1,7 @@
+<!-- source: sdd-opt-v1 AX_POLISH_MODE (risk-first critique) -->
+<Axiom id="AX_POLISH_MODE">
+  Default dispatch is `polish: off` — report only CRITICAL and MAJOR (production-threatening logic /
+  security / contract / alignment defects). MINOR / INFO never drive the loop or the verdict; they ride
+  along in a separate non-blocking list ONLY when the operator asks for nits ("шлифуй" / "polish"). A
+  clean artifact with a pile of suppressed nits is still CLEAN — do not let polish noise stall the loop.
+</Axiom>

package/dist/ai/kit/axiom/critic/ax-product-architect-lens.xml

@@ -0,0 +1,13 @@
+<!-- source: SDD v2 — critic as product architect, not proofreader -->
+<Axiom id="AX_PRODUCT_ARCHITECT_LENS">
+      Critique like an architect who owns the business and product goals — not a proofreader. Code has no value in itself; its value is defined by its CONSUMERS (the exception is a technical library, whose consumers are other developers). So judge the design against real consumer / product value, never against polish.
+
+      The primary questions, AHEAD of any hygiene check:
+      - Does this design actually serve the stated product goal — and the goal behind the goal, the consumer need it exists for?
+      - Is the goal drawn too NARROW? Look just past the stated edges — the adjacent need, the case at the boundary, the consumer the current framing silently excludes. WIDEN the goal where it should be wider; do not merely confirm it.
+      - What fundamental design / logic blind spots would make the result miss its purpose? Not the small defects — tests and coverage own implementation quality.
+
+      Judge value in the CONTEXT of the dependent system — read the Vision / Goals of the specs this one depends on (gathered by a tool, `AX_ISOLATION`), never critique a spec in isolation: a design can be internally clean yet wrong for the system it plugs into.
+
+      Lead with these. The structural dimensions (boundary, entities, contracts, …) are SUPPORTING, not the point. A finding that only polishes — without touching goal, value, or a real blind spot — does not belong here (`AX_POLISH_MODE`).
+    </Axiom>

package/dist/ai/kit/axiom/critic/ax-read-only.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_READ_ONLY">Read artifact + parent spec. Write text output. NEVER edit files — orchestrator applies edits.</Axiom>

package/dist/ai/kit/axiom/critic/ax-uncertainty-is-signal.xml

@@ -0,0 +1,2 @@
+<!-- source: ai/directives/sdd/critic-protocol.xml -->
+<Axiom id="AX_UNCERTAINTY_IS_SIGNAL">"I don't understand X" is valid output. Uncertainty = underspecification.</Axiom>

package/dist/ai/kit/axiom/critic/ax-uncomfortable-questions.xml

@@ -0,0 +1,12 @@
+<!-- source: sdd/discovery + module-decomposition (merged) -->
+<Axiom id="AX_UNCOMFORTABLE_QUESTIONS">
+  Every meaningful frame includes ≥1 uncomfortable question — the kind that exposes hidden
+  assumptions, degradation paths, or trust boundaries. Canonical seeds:
+  - What is the canonical source of truth for this entity / capability?
+  - What happens on dependency unavailability (graceful degradation vs hard failure)?
+  - Where does simulation end and real runtime begin?
+  - Who validates input at this trust boundary?
+  - Which assumption, if wrong, invalidates the design?
+
+  Skipping uncomfortable questions = false consensus.
+</Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-ax-tree-as-primary-vision.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_AX_TREE_AS_PRIMARY_VISION">
+      `page.ariaSnapshot()` is the primary perceptual channel for an agent. It emits a YAML representation of the accessibility tree — the same structure that `getByRole()` queries and `toMatchAriaSnapshot()` asserts. So the AX tree is the lingua franca across explore → interact → assert.
+
+      Pixel-level vision (screenshots, visual diff) is a secondary channel reserved for layout-only concerns. Choosing it as the primary signal binds the test to rendering pipelines that vary across machines.
+    </Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-codegen-is-recorder-not-author.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_CODEGEN_IS_RECORDER_NOT_AUTHOR">
+      `playwright codegen` records interactions but its output is NOT directly committable. The generated locators are typically CSS / nth-child / XPath chains — fragile and implementation-coupled. The agent reviews codegen output and replaces every selector with a role-based equivalent derived from the AX tree before any line of it lands in a committed file.
+    </Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-dev-server-precondition.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_DEV_SERVER_PRECONDITION">
+      Every CLI command depends on a running application. The agent confirms the dev server is reachable (HTTP 200 at the expected URL, or the project's known boot-complete signal) BEFORE issuing the first Playwright call. Skipping this turns the first `page.goto` failure into a confusing «Playwright is broken» investigation instead of a one-line «start the dev server» fix.
+    </Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-explore-before-author.xml

@@ -0,0 +1,6 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_EXPLORE_BEFORE_AUTHOR">
+      Exploration MUST precede authoring. Agent first sees the page through `page.ariaSnapshot()`, then interacts through `page.getByRole(...)`, then captures the post-state. Only after this loop completes does codification into a committed test file begin.
+
+      A locator that has never been resolved against a running page is a guess; committing it bypasses the only ground truth the test has.
+    </Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-explore-loop-has-four-steps.xml

@@ -0,0 +1,10 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_EXPLORE_LOOP_HAS_FOUR_STEPS">
+      The exploration loop is fixed at four steps and runs to completion before any test file is touched:
+      1. **Explore** — `page.goto(url)`; `page.ariaSnapshot()`; read structure.
+      2. **Interact** — `page.getByRole(...).click()` / `.fill()` / `.press()`; re-capture `ariaSnapshot()`; observe delta.
+      3. **Verify** — compare observed structure against expected intent; if mismatch, fix the component first, restart, re-explore.
+      4. **Capture** — record the final AX snapshot and any required screenshots as the basis for the committed test.
+
+      Skipping a step (e.g. interacting without re-snapshotting) hides the contract drift the loop exists to surface.
+    </Axiom>

package/dist/ai/kit/axiom/e2e/ax-cli-headless-for-agent.xml

@@ -0,0 +1,4 @@
+<!-- source: ai/directives/testing/playwright-cli.xml -->
+<Axiom id="AX_CLI_HEADLESS_FOR_AGENT">
+      Every CLI exploration session for an agent runs headless. The `--headed` / `--ui` / `--debug` modes are human-only — they assume a sighted operator at the terminal. An agent that opens a headed window has no consumer for the visual output and burns the session waiting for user input that will never arrive.
+    </Axiom>