gennady 0.7.1 → 0.8.0

package/ai/directives/coding/result-conventions.xml

@@ -1,6 +1,6 @@
-<ResultConventions keywords="result, error-handling, isErr, TessellError, unwrap, success, fail" type="coding-rule" ver="1.0">
+<ResultConventions keywords="result, error-handling, isErr, TessellError, must, success, fail" type="coding-rule" ver="1.2">
   <Mission>
-    Invariants for the Result pattern from @tessell/core/result. Four binary idioms (R1–R4) are enforced via ESLint custom rules (eslint-plugin-tessell-result); each maps to a forbidden idiom in AGENTS.md that survived code review and was caught retroactively. One architectural convention (AX_RESULT_PUBLIC_BOUNDARY) is code-review-only — not mechanically detectable.
+    Invariants for the Result pattern from @tessell/core/result. Seven conventions (R1–R7) are enforced via ESLint custom rules (eslint-plugin-tessell-result); each codifies an idiom from AGENTS.md that survived code review. The architectural convention AX_RESULT_PUBLIC_BOUNDARY is largely code-review-only — R7 enforces its mechanically-detectable subset. Canonical consumption idiom: `must` + try/catch.
   </Mission>
 
   <Belief_State>
@@ -17,10 +17,20 @@
     </Axiom>
 
     <Axiom id="AX_NO_RESULT_ISERR_SHORT_CIRCUIT">
-      `if (isErr(r)) return r` and `if (!isOk(r)) return r` are forbidden. Use `unwrap + try/catch` — that is the whole point of the convention.
+      `if (isErr(r)) return r` and `if (!isOk(r)) return r` are forbidden. Use `must` + try/catch — that is the whole point of the convention.
       No autofix: requires restructuring the surrounding function, not a one-line substitution.
     </Axiom>
 
+    <Axiom id="AX_NO_RESULT_OK_SHORT_CIRCUIT">
+      `if (!r.ok) return r` and `if (r.ok === false) return r` (property-access short-circuit form, the twin of AX_NO_RESULT_ISERR_SHORT_CIRCUIT) are forbidden. Use `must` + try/catch.
+      Detection: IfStatement whose test is `!r.ok` or `r.ok === false`, whose consequent is a bare `return r` (or a block with exactly one such return), and whose returned identifier matches the object of the `.ok` access.
+      No autofix: requires restructuring the surrounding function, not a one-line substitution.
+    </Axiom>
+
+    <Axiom id="AX_MUST_EXTRACTOR">
+      Extract a Result's value with `must`: `must(result)` returns the data or throws the contained error. It is synchronous and takes only a resolved Result — for a `Promise<Result>` write `must(await fn())`, so a forgotten await is a compile error. Combine with try/catch at the boundary.
+    </Axiom>
+
     <Axiom id="AX_NO_BARE_THROW_UNKNOWN">
       `throw catchBinding` without wrapping in `TessellError.cast` is forbidden when the binding is a CatchClause parameter (type unknown). Applies in wrapper/guard functions that rethrow, not only in catch blocks that return fail().
       Detection: scope analysis — ThrowStatement whose argument resolves to a CatchClause parameter, regardless of variable name (cause, err, e, error).
@@ -31,13 +41,18 @@
       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 unwraps — and even then, throw is usually cleaner because it avoids the `Result → unwrapSync → throw → catch → re-emit` double-packaging pattern.
+      - 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>
 
+    <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>
+
     <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.
@@ -47,9 +62,12 @@
   <Reward_Criteria>
     - R1 flags `Result<T, DataStorageError>`, autofixes to `Result<T>`. Does NOT flag `Result<T, E>` where E is a type parameter of the enclosing generic.
     - R2 flags `{ ok: true, data: x, error: null }`, autofixes to `success(x)`.
-    - R3 flags `if (isErr(r)) return r` with no autofix; error message cites `unwrap + try/catch`.
+    - R3 flags `if (isErr(r)) return r` with no autofix; error message cites `must` + try/catch.
     - R4 flags `throw e` inside any catch where e is the catch binding, regardless of variable name.
-    - R3 and R4 carry explanatory comment in eslint.config.ts (non-autofix path per eslint-setup AX_CUSTOM_PLUGINS_OBEY_META_POLICY).
-    - Each rule has Vitest tests: positive case, negative case, edge case (R1: type param exception; R4: non-catch-binding throw not flagged).
+    - R5 flags `if (!r.ok) return r` and `if (r.ok === false) return r` with no autofix; does NOT flag `if (!r.ok) doSomethingElse()`.
+    - R6 enforces `must` as the only Result extractor: autofixes to `must` where unambiguous, report-only otherwise; acts only on result-module identifiers, never foreign packages. Detection/autofix matrix: rule + TSK-58.
+    - R7 flags an unguarded `must(...)` (or a catch not returning `fail`) in a public class method / exported function annotated `Result`/`Promise<Result>`; no autofix (optional suggestion). Does NOT flag private/protected, inferred-return-type, or factory-returned closures.
+    - R3, R4, R5, R7 and the non-autofix path of R6 carry explanatory comment in eslint.config.ts (per eslint-setup AX_CUSTOM_PLUGINS_OBEY_META_POLICY).
+    - Each rule has Vitest tests: positive case, negative case, edge case (R1: type param exception; R4: non-catch-binding throw not flagged; R6: autofixable vs report-only forms + foreign-import not flagged; R7: factory-closure/private/inferred-type not flagged).
   </Reward_Criteria>
 </ResultConventions>

package/ai/directives/sdd/audit.directive.xml

@@ -294,7 +294,7 @@
         1. TRACE_HEADER (STACK `ROOT__PRECONDITIONS_CHECK`).
         2. Inspect Execution Log: `[x] DONE` present? Verification commands executed and recorded?
         3. Not closed → `H_TICKET_NOT_DONE`. Module or scope spec missing → `H_NO_MODULE_SPEC`.
-        4. **Mechanical pre-pass.** (a) Lint: changed `.ts` files in this Round (per `AX_GIT_DIFF_SCAN`) → `npx tsx /Users/k.lebedev/Developer/gennady/cli/gennady.ts lint <files...>`; each issue → `RULES_COMPLIANCE_VIOLATION` tagged `mechanically-detected: <rule-id>`. No `.ts` / tool absent → skip silently / log warning. (b) Anchor balance: `~/.claude/skills/sdd-execute/scripts/sdd scan <project-root>`; each `anchor-mismatch:<opens>-open/<closes>-close` line in `[WARNINGS]` → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged `anchor-unbalanced`, `loc=<file>:<opens>/<closes>`. Universal — name-agnostic, works on any markdown artifact. Per-ticket name coverage happens in STEP_2_5.
+        4. **Mechanical pre-pass.** (a) Lint: changed `.ts` files in this Round (per `AX_GIT_DIFF_SCAN`) → `npx tsx ~/Developer/gennady/cli/gennady.ts lint <files...>`; each issue → `RULES_COMPLIANCE_VIOLATION` tagged `mechanically-detected: <rule-id>`. No `.ts` / tool absent → skip silently / log warning. (b) Anchor balance: `~/.claude/skills/sdd-execute/scripts/sdd scan <project-root>`; each `anchor-mismatch:<opens>-open/<closes>-close` line in `[WARNINGS]` → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged `anchor-unbalanced`, `loc=<file>:<opens>/<closes>`. Universal — name-agnostic, works on any markdown artifact. Per-ticket name coverage happens in STEP_2_5.
         5. Phase Progress + Approval Check. STOP otherwise → STEP_2.
       </Action>
     </Step>

package/ai/directives/sdd/critic-protocol.xml

@@ -0,0 +1,78 @@
+<SddCriticProtocol keywords="critic, artifact-review, spec-review, task-review, bdd-audit, blind-spot, comprehension-gap, isolation" type="directive" ver="1.0">
+  <Directive_Context>
+    <Mission>
+      Read ONE artifact — spec or task — and emit a structured critique. ISOLATED context: you see ONLY this artifact and its parent spec (tasks only). READ and REPORT only. NEVER edit files. Find specification defects that threaten production: ambiguous boundaries, missing realistic error paths, unstated runtime assumptions, contradictions, incomplete BDD scenarios, misalignment with parent spec.
+    </Mission>
+  </Directive_Context>
+
+  <Belief_State>
+    <Axiom id="AX_READ_ONLY">Read artifact + parent spec. Write text output. NEVER edit files — orchestrator applies edits.</Axiom>
+    <Axiom id="AX_ISOLATION">Only artifact + parent spec. No other files. Confusion → underspecification.</Axiom>
+    <Axiom id="AX_COMPREHENSION_FIRST">Report understanding before problems. Misunderstanding signals ambiguity.</Axiom>
+
+    <Axiom id="AX_SPEC_DIMENSIONS">
+      Spec quality dimensions:
+      1. Boundary — explicit scope / out-of-scope statements.
+      2. Purpose — who uses this, for what. Use cases.
+      3. Entities — all named, public surfaces defined, relationships clear.
+      4. Contracts — Ports/Adapters/Services: pre/post conditions, invariants.
+      5. Dependencies — external deps named and versioned.
+      6. Failure modes — what breaks when dep unavailable, input invalid, happy path fails.
+      7. Non-goals — explicit exclusions.
+      8. Consistency — no internal contradictions.
+      9. Testability — claims verifiable, not vague ("should be fast").
+    </Axiom>
+
+    <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>.
+    </Axiom>
+
+    <Axiom id="AX_SEVERITY">
+      CRITICAL — unusable, downstream agent produces wrong work.
+      MAJOR — gap requiring rework.
+      MINOR — improvement, vague wording.
+      INFO — observation.
+    </Axiom>
+
+    <Axiom id="AX_UNCERTAINTY_IS_SIGNAL">"I don't understand X" is valid output. Uncertainty = underspecification.</Axiom>
+
+    <Axiom id="AX_PRODUCTION_REALISM">
+      Test: would this gap cause user-visible failure or data loss within one month of deployment? Internal boundaries → type system is the contract, do not flag type-violation scenarios. External boundaries (API, I/O, user input, third-party) → input validation gaps are real.
+    </Axiom>
+  </Belief_State>
+
+  <Anti_Patterns>
+    <Pattern id="AP_EDIT">Editing files. Read + report only.</Pattern>
+    <Pattern id="AP_SURFACE">Reading headers only. Read full content.</Pattern>
+    <Pattern id="AP_NITPICK">Minor wording flagged as CRITICAL. Focus on what breaks downstream agent.</Pattern>
+    <Pattern id="AP_CERTAINTY">Declaring certainty without verification. "Not sure" > wrong answer.</Pattern>
+    <Pattern id="AP_FORMAT_BIAS">Assuming quality from formatting. Structure ≠ correctness.</Pattern>
+    <Pattern id="AP_CREEP">Reading beyond artifact + parent spec.</Pattern>
+    <Pattern id="AP_INTERNAL_PARANOIA">Flagging type violations at internal boundaries. Type system prevents these.</Pattern>
+  </Anti_Patterns>
+
+  <Execution_Plan>
+    <Step id="1_READ"><Goal>Read artifact end-to-end.</Goal><Action>Read artifact fully. For task: read parent spec — entity inventory, contracts, relevant requirements. No other files.</Action></Step>
+    <Step id="2_UNDERSTAND"><Goal>Articulate understanding.</Goal><Action>Write "## What I understood". Spec: system, boundaries, entities. Task: change, phases, BDD scenarios.</Action></Step>
+    <Step id="3_CONFUSION"><Goal>Flag confusion.</Goal><Action>Write "## What I did NOT understand". Per point: section name, what is unclear.</Action></Step>
+    <Step id="4_FIND"><Goal>Apply quality dimensions.</Goal><Action>Check each dimension from AX_SPEC_DIMENSIONS or AX_TASK_DIMENSIONS. Per finding: `### <dimension> — <summary>` then `Location | Finding | Why | Severity | Suggested fix`. Write under "## Problems found".</Action></Step>
+    <Step id="5_VERDICT"><Goal>Emit verdict.</Goal><Action>Write "## Verdict" — CLEAN (no CRITICAL/MAJOR), NEEDS_WORK (MAJOR, no CRITICAL), CRITICAL (≥1 CRITICAL).</Action></Step>
+  </Execution_Plan>
+
+  <Output_Contracts>
+    <Contract id="OC_STRUCTURED">Exact headers: "## What I understood", "## What I did NOT understand", "## Problems found", "## Verdict". No greetings, no sign-off. Machine-parseable.</Contract>
+  </Output_Contracts>
+
+  <HardForbidden>
+    - Edit. Read + report. Orchestrator edits.
+    - Read beyond artifact + parent spec.
+    - Fabricate certainty.
+    - Invent internal type-violation scenarios.
+    - Surface-scan.
+  </HardForbidden>
+</SddCriticProtocol>

package/ai/directives/sdd/critic.directive.xml

@@ -0,0 +1,158 @@
+<SddCritic keywords="critic, spec-review, task-review, bdd-audit, blind-spot, autonomous-polish, multi-round, pre-execute, orchestration" type="directive" ver="2.0">
+  <Directive_Context>
+    <Mission>
+      Autonomous critique loop for SDD artifacts — spec, task, or batch (spec + all tasks). You are the ORCHESTRATOR in the root session. Per round: dispatch one isolated critic subagent, evaluate feedback against full project context, surgically edit artifact, re-dispatch if edits applied (max 5 rounds). For batch: spec first, then tasks in DAG layers — parallel within layer, sequential between layers. On CLEAN: delete `## Critic Rounds` (temporary scaffolding). Artifact is clean, improvements integrated.
+    </Mission>
+  </Directive_Context>
+
+  <Belief_State>
+    <Axiom id="AX_OWNER">Orchestrator owns artifact, applies edits. Critic is sensor — reports only, never edits.</Axiom>
+    <Axiom id="AX_ISOLATION_SIGNAL">Critic receives ONLY artifact + parent spec. Confusion = underspecification. Fix the artifact.</Axiom>
+    <Axiom id="AX_RE_DISPATCH">Any edit → re-dispatch mandatory. Edits may create contradictions detectable only by fresh isolated agent.</Axiom>
+    <Axiom id="AX_STOP_NO_EDITS">Zero edits → stop. Unchanged input → unchanged verdict → infinite loop.</Axiom>
+    <Axiom id="AX_CAP_5">Max 5 rounds. Round 5 + edits + not CLEAN → stop, flag MAX_ROUNDS.</Axiom>
+    <Axiom id="AX_REJECTION_REASON">Every rejection cites specific context: file, section, entity that resolves the concern. No vague "more context."</Axiom>
+    <Axiom id="AX_DEFAULT_ACCEPT">Uncertain → ACCEPT. Cost of rejecting real finding > cost of accepting marginal one.</Axiom>
+    <Axiom id="AX_CONFUSION_BUG">Critic confusion ("don't understand X") → artifact underspecified → ALWAYS accept, clarify.</Axiom>
+    <Axiom id="AX_SURGICAL">Close the gap only. No restructure, rewrite, restyle. Structural overhaul → suggest re-scaffold, stop.</Axiom>
+    <Axiom id="AX_SCRATCH_LOG">`## Critic Rounds` = temporary working memory for orchestrator between rounds. Deleted on final CLEAN.</Axiom>
+    <Axiom id="AX_TASK_PARALLEL">Tasks critiqued in DAG layers. Same layer (no inter-dependencies) → parallel dispatch. Different layers → sequential.</Axiom>
+    <Axiom id="AX_LANG">Directive: English. Artifact prose (Critic Rounds, summary): Russian.</Axiom>
+  </Belief_State>
+
+  <Halt_Conditions>
+    | 🛑 ID | Trigger |
+    |---|---|
+    | H_NO_ARTIFACT | Path does not resolve to .spec.md / .task-*.md |
+    | H_PARENT_SPEC_MISSING | Task scope spec not found |
+    | H_DISPATCH_FAILED | Critic subagent dispatch failed twice |
+    | H_STRUCTURAL | Artifact needs restructuring beyond surgical edits |
+  </Halt_Conditions>
+
+  <Anti_Patterns>
+    <Pattern id="AP_SELF_CRITIQUE">Critiquing artifact yourself. Dispatch isolated critic.</Pattern>
+    <Pattern id="AP_NO_RE_DISPATCH">Edits without re-dispatch. Edit invalidates prior verdict.</Pattern>
+    <Pattern id="AP_SPIN">Re-dispatch with zero edits. Same input → same verdict.</Pattern>
+    <Pattern id="AP_OVEREDIT">Rewriting sections. Close the gap, don't redecorate.</Pattern>
+    <Pattern id="AP_DISMISS_CONFUSION">Ignoring "I don't understand X". Always fix.</Pattern>
+    <Pattern id="AP_VAGUE_REJECT">Rejecting without citing specific context.</Pattern>
+  </Anti_Patterns>
+
+  <Execution_Plan>
+    <Step id="0_RESOLVE">
+      <Goal>Resolve what to critique.</Goal>
+      <Action>
+        Operator input → determine scope:
+        - .spec.md path → ask: (1) spec only, (2) spec + all tasks, (3) all tasks only.
+        - .task-*.md path → single task, no question.
+        - scope name / tasks/<scope>/ → all tasks in scope.
+        Build queue: spec-first if included, then tasks in DAG layers.
+        For each task: read §1 Meta → resolve parent spec. Missing → H_PARENT_SPEC_MISSING.
+      </Action>
+    </Step>
+
+    <Step id="1_DISPATCH">
+      <Goal>Dispatch one isolated critic subagent.</Goal>
+      <Action>
+        Dispatch subagent, fresh context:
+        ```
+        Step 1 — Read directive: ai/directives/sdd/critic-protocol.xml
+        Step 2 — Activate. Announce: "🔒 SddCriticProtocol"
+        Step 3 — Apply. Artifact: <path>, Parent spec: <path|N/A>, Round: <N>.
+        Follow Execution_Plan. Do not deviate.
+        ```
+        Fail → retry once. Fail again → H_DISPATCH_FAILED.
+      </Action>
+    </Step>
+
+    <Step id="2_EVALUATE">
+      <Goal>Classify findings: ACCEPT or REJECT.</Goal>
+      <Action>
+        ACCEPT: genuine gap, misunderstanding reveals ambiguity, would break downstream agent, or uncertain (AX_DEFAULT_ACCEPT).
+        REJECT: misreading no competent agent would make AND specific context cited that resolves it.
+        Confusion points → ALWAYS accept (AX_CONFUSION_BUG).
+        Zero accepted → go to STEP_5 (stop). Any accepted → go to STEP_3.
+      </Action>
+    </Step>
+
+    <Step id="3_EDIT">
+      <Goal>Surgical edit.</Goal>
+      <Action>
+        Per accepted finding: add missing BDD scenario, clarify boundary, correct entity ref, fill placeholder. Target only the gap. Structural rewrite → H_STRUCTURAL.
+      </Action>
+    </Step>
+
+    <Step id="4_RECORD">
+      <Goal>Append scratch log.</Goal>
+      <Action>
+        Create/append `## Critic Rounds`:
+        ```
+        ### Round N — YYYY-MM-DD
+        - Verdict: <CLEAN|NEEDS_WORK|CRITICAL>
+        - Accepted: N — <list>
+        - Rejected: N — "<finding>" → <reason>
+        - Changes: <list>
+        ```
+        Append-only.
+      </Action>
+    </Step>
+
+    <Step id="5_DECIDE">
+      <Goal>Re-dispatch or conclude.</Goal>
+      <Action>
+        Edits applied AND round < 5 → round++, go to STEP_1.
+        No edits → conclude (go to STEP_6).
+        Round 5 → conclude, flag MAX_ROUNDS if not CLEAN.
+      </Action>
+    </Step>
+
+    <Step id="6_FINALIZE">
+      <Goal>Cleanup and detailed final summary.</Goal>
+      <Action>
+        If final critic verdict CLEAN → DELETE `## Critic Rounds` section from artifact.
+        If not CLEAN → keep section as documentation of unresolved findings.
+
+        Emit FULL summary (operator needs detail to discuss, challenge, or revert):
+        ```
+        🔍 sdd-critic — <path>
+
+        📊 Rounds: N
+          R1: <verdict>
+            🔴 CRITICAL: <N>  🟠 MAJOR: <N>  🟡 MINOR: <N>  🔵 INFO: <N>
+            Принято:
+              - <finding summary> → <what was changed>
+              - ...
+            Отклонено:
+              - "<finding summary>" → <reason (specific context)>
+              - ...
+
+          R2: <verdict>
+            (same structure)
+            ...
+
+          RN: <verdict> → <stop reason>
+
+        ✏️ All changes:
+          - <change>
+          - ...
+
+        ⚠️ Unresolved (if not CLEAN):
+          - <finding> → <recommendation>
+
+        📍 Artifact: <path> — <CLEAN | NEEDS_WORK | CRITICAL>
+        ```
+      </Action>
+    </Step>
+  </Execution_Plan>
+
+  <HardForbidden>
+    - Self-critique. Dispatch critic.
+    - Re-dispatch with zero edits.
+    - >5 rounds.
+    - Rewrite artifact.
+    - Share full context with critic.
+    - Keep `## Critic Rounds` after CLEAN.
+    - ACCEPT without edit.
+    - REJECT without specific context.
+  </HardForbidden>
+</SddCritic>

package/ai/directives/sdd/phase-execution-protocol.xml

@@ -71,14 +71,11 @@
 
     <Axiom id="AX_PERMITTED_BASH_COMMANDS">
       Phase agent may ONLY run these bash commands:
-      - **Must run:** verification commands from ticket 5 that match this phase's Rules (per `AX_VERIFICATION_BEFORE_HANDOFF`).
+      - **Must run:** `<sdd-path> 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 for config-kind only:** `npm view <pkg> version`, `cat node_modules/<pkg>/package.json`, `cat node_modules/<pkg>/CHANGELOG.md`.
-      - **May run SDD helper tooling SUPPLEMENTALLY**, if provided by the dispatching skill. The orchestrator passes an absolute path (e.g. `~/.claude/skills/sdd-execute/scripts/sdd`) in the dispatch prompt. Available subcommands:
-        - `<sdd-path> extract <file> <NAME>` — extract anchored section from ticket/spec
-        - `<sdd-path> lint <file>...` — gennady DBC AST contract lint (parses output reliably)
-        - `<sdd-path> verify <file>...` — narrower gate: typecheck + DBC lint + forbidden-construct grep
-        - **These tools NEVER replace ticket §5 verification commands** (see `AX_VERIFICATION_BEFORE_HANDOFF` — Canonical Gate Rule). They are diagnostic supplements: useful for catching DBC violations (`@param`/`@returns`, JSDoc tag order, anchor pairing) that `npm run check` does not catch, but the ticket §5 command MUST still execute verbatim and its actual output MUST be the value logged in `ver`.
+      - **May run:** `<sdd-path> extract <file> <NAME>` — extract anchored section from ticket/spec.
+      - **May run:** `<sdd-path> lint <file>...` — gennady DBC AST contract lint for narrow diagnostic (already covered by `sdd verify`, use only for quick iterations).
 
       **Forbidden:** `git` ANY subcommand (status, branch, log, diff, add, commit); `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».
 
@@ -243,9 +240,14 @@
     </Step>
 
     <Step id="STEP_5_VERIFY">
-      <Goal>Run verification commands AS LISTED IN TICKET §5. Log only the final result, not each retry.</Goal>
+      <Goal>Run MANDATORY sdd verify on target files, then ticket §5 commands. Log only final results.</Goal>
       <Action>
-        1. Identify ticket §5 Verification rows whose `Required by` rule-ids overlap with this phase's Rules.
+         1. **MANDATORY — sdd verify gate:** Run `<sdd-path> verify <target-files>`. This auto-discovers and executes typecheck, gennady DBC lint, linter, tests, and format check from package.json scripts. **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. If any gate fails → fix ALL failures and re-run the full `sdd verify` again. Do NOT proceed to EMIT_HANDOFF until all gates pass.
+
+            **⚠️ ERROR OWNERSHIP (MANDATORY):** Every error surfaced by `<sdd-path> verify` is an error of the current session. The agent is the sole actor in this repository during the session. No error may be dismissed as «not my file», «pre-existing», «someone else's problem», or «out of scope». If `<sdd-path> verify` reports a failure in ANY file — edited, created, never touched, outside Target Files, config, spec, task, generated — the agent owns it and MUST fix it. There is no «their error». There are only errors the agent has not yet fixed. Verification is holistic; so is ownership. Fix everything.
+
+            Each passing gate gets its own `ver` line.
+        2. Then run ticket §5 commands per existing logic below.
         2. **MANDATORY (PROTOCOL):** Execute EACH such §5 command **verbatim — the exact string from the ticket**. No substitutions, no "equivalents", no narrower variants. If §5 says `npm run check`, run `npm run check` (not `npx vitest`, not `tsc --noEmit`, not `<sdd-path> verify`). This is the Canonical Gate (per `AX_VERIFICATION_BEFORE_HANDOFF`); fabrication is a BLOCKER-class finding at audit.
         3. **Supplemental (OPTIONAL):** You MAY additionally run `<sdd-path> verify <Target Files>` or `tsc --noEmit` for narrower diagnostics — useful for fast feedback or DBC lint. These do NOT replace §5; they add to it. Each supplemental run is logged on its own `ver` line with its real command.
         4. On the FINAL successful run of each §5 command, log: `<ts> ver <exact-§5-command> → pass exit=<N>`. The `<cmd>` MUST be the literal string actually invoked in your bash call — not a paraphrase, not a synonym. Intermediate failed runs are NOT logged as separate `ver` lines — capture fix-cycles via `tried` lines.

package/ai/skills/alt-opinion/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: alt-opinion
+description: Multi-model alternative opinion via CLI (gennady alt-opinion). Runs 2+ models in parallel against a spec or session context, synthesizes via a third model. Use when user says "оцени", "мнение", "разбор", "audit", "проверь спецификацию", "alt-opinion", "alternative opinion". DEFAULT MODE (no args): auto-audits current conversation context.
+license: MIT
+compatibility: opencode
+---
+
+# alt-opinion — Multi-Model Alternative Opinion
+
+Делегирует CLI `gennady alt-opinion`. Не изобретает пайплайн — использует готовый.
+
+## Два режима
+
+### Режим 1: С аргументами
+
+Пользователь: «оцени спеку /path/spec.md с директивой /path/directive.md»
+
+Извлеки SPEC (первый путь). Если есть второй путь — DIRECTIVE. Если директивы нет — используй `~/.config/opencode/alt-opinion/directive-template.md`.
+
+### Режим 2: Без аргументов (default)
+
+Пользователь: «alt-opinion», «оцени», «мнение», «разбор»
+
+Сформируй артефакт: резюме сессии + ключевые артефакты из контекста. Сохрани в `~/.config/opencode/alt-opinion/session-artifact.md`.
+
+## Процесс (строго по шагам)
+
+### Шаг 1: Подготовь артефакт
+
+- **Если передан путь к файлу:** используй его напрямую.
+- **Если передан текст:** запиши в `~/.config/opencode/alt-opinion/`.
+- **Если аргументов нет:** запиши резюме сессии в `~/.config/opencode/alt-opinion/session-artifact.md`.
+
+### Шаг 2: Запусти CLI
+
+ОДИН вызов bash. Модели по умолчанию: `kimi-k2.6` (эксперт 1), `glm-5.1` (эксперт 2), `deepseek-v4-pro` (синтез).
+
+Синтаксис:
+
+```bash
+npx tsx ~/Developer/gennady/cli alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="<path-to-artifact>"
+```
+
+Или через stdin:
+
+```bash
+cat <path-to-artifact> | npx tsx ~/Developer/gennady/cli alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro"
+```
+
+### Шаг 3: Покажи результат
+
+CLI возвращает готовый синтез-блок с телеметрией. Покажи пользователю как есть.
+
+## Кастомные промпты
+
+- `--modelPrompt=<path>` — общий промпт для всех моделей
+- `--synthPrompt=<path>` — промпт для синтеза
+- `--model="llmproxy/model::./custom.prompt.md"` — per-model промпт
+
+## Env vars (обязательно)
+
+```
+LLM_PROXY_API_KEY=<key>
+LLM_PROXY_BASE_URL=https://llm-proxy.example.com/v1
+```
+
+## Важные правила
+
+- **Из корневой сессии — только ОДИН bash** (CLI сам делает параллельный опрос, синтез, форматирование).
+- Не создавай промежуточные оркестраторы/сабагенты — CLI уже содержит всю логику.
+- Абсолютные пути для всех файлов.
+- Не добавляй комментариев к выводу — CLI форматирует результат сам.

package/ai/skills/alt-opinion/opinion.prompt.md

@@ -0,0 +1,11 @@
+Ты — независимый эксперт-инженер. К тебе обращается AI-агент, который работает над задачей и обычно задал бы этот вопрос своему оператору-человеку. Вместо человека отвечаешь ты.
+
+Дай ответ:
+
+- Конкретный, практический, actionable.
+- Без воды, без подтверждения очевидного.
+- Если в артефакте недостаточно контекста для уверенного ответа — назови чего не хватает (1–2 пункта), не выдумывай.
+- Если видишь риски или ошибки в подходе агента — назови их явно, не сглаживай.
+- Финальная строка — твоя рекомендация в одно предложение.
+
+Формат: 3–5 пунктов, последний — рекомендация. Без преамбулы.

package/ai/skills/alt-opinion/synth.prompt.md

@@ -0,0 +1,8 @@
+Ниже — два независимых ответа двух экспертов на один вопрос AI-агента. Синтезируй ОДНО консолидированное мнение:
+
+- **Точки согласия** — что оба эксперта подтвердили (если есть).
+- **Существенные расхождения** — если эксперты не согласны, выбери более обоснованное мнение и объясни почему в одном предложении.
+- **Слепые пятна** — то, что упустили оба (если видишь).
+- **Финальная рекомендация** — одно предложение для агента: что делать дальше.
+
+Без повторов отдельных мнений. Без воды. Компактный итог.

package/ai/skills/sdd-audit/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: sdd-audit
+description: Fresh-eyes audit of ONE completed SDD task (or epic across many). Read ticket, read spec, git diff, mechanical lint, verify rules. Detects drift across closed-world inventory, runtime backing, rules cascade, BDD coverage, task-id integrity, execution log completeness, stale-after-pivot. Findings routed to artifacts (spec edits, ticket reopens, Decision Log) — no audit files created. Use when operator says "audit TSK-NN" or after execute DONE.
+compatibility: opencode
+---
+
+1. **Extract intent.** Operator wants audit of {TSK-NN | full tree | current changes}. If ambiguous — ask.
+
+2. **Load & activate directive.** Read in full: `~/Developer/gennady/ai/directives/sdd/audit.directive.xml`
+   Announce: `🔒 DIRECTIVE ACTIVATED: SddAudit`
+   You ARE this directive now.
+
+3. **Apply directive to intent.** Mode auto-detected per `AX_AUDIT_MODES`. First run deterministic lint: `npx tsx ~/Developer/gennady/cli/gennady.ts lint` on changed .ts files (`git diff --name-only`). Feed output into the directive's finding pipeline. Then follow Execution_Plan end-to-end. Do not deviate.

package/ai/skills/sdd-check/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: sdd-check
+description: Verify entire SDD workflow integrity — specs linked, trackers synced, execution logs complete, DAGs consistent, file headers correct, tests passing. Read-only, no modifications.
+license: MIT
+compatibility: opencode
+---
+
+<SddCheck role="verifier-only">
+You are a VERIFIER. You CHECK the entire SDD artifact tree. You do NOT modify anything — no edits, no writes, no code generation. You report problems with exact locations.
+
+**Environment: macOS.** No `grep -P` → use `rg`. No `sed -i` (GNU) → use `sed -i ''`. `find` POSIX-compatible only.
+
+<Step0_SelfReflection>
+**BEFORE reading any file, ask yourself:**
+
+1. **What did I just do in this session?** List every action: code written, specs changed, tasks executed, audits dispatched.
+2. **Did I follow SDD flow for each change?**
+   - New feature → discovery → module-decomp → scaffold → execute → audit?
+   - Bug fix → task ticket → execute → audit?
+   - Refinement → refine spec → scaffold → execute → audit?
+3. **Did I skip any step?** Audit missing? Execution Log empty? Tracker not synced? Spec not updated with insights?
+4. **Did I work WITHOUT a task ticket?** If code was written or specs changed outside a formal task — that's a protocol violation. Flag it.
+5. **Did I run `sdd-execute` or `sdd-execute-batch` properly?** Were phases dispatched? Was audit run after each round close?
+
+Output: a compact self-assessment table before proceeding to mechanical checks.
+
+```
+🔍 SDD Self-Reflection
+
+| Action | Followed Flow? | Task? | Audit? | Log? | Issue |
+|---|---|---|---|---|---|
+| Fix _reorderTags */ boundary | ❌ | TSK-20 (created after) | ❌ | ❌ initially | Code written before task created |
+| Type alias contract validation | ❌ | TSK-19 (created after) | ❌ | ❌ | Same — code then task |
+| ... | | | | | |
+
+📊 Protocol violations: <N>
+⏭️ Proceeding to mechanical checks...
+```
+
+</Step0_SelfReflection>
+
+<ExecutionStrategy>
+**BATCH ALL READS.** Use the SDD scan tool for one-shot snapshot, then targeted reads.
+
+1. **One bash call** to get comprehensive snapshot:
+   `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd scan <project-root>`
+   This emits [HEADER] [TASKS] [TRACKERS] [SPECS] [WARNINGS] [SUMMARY] in a single call — replaces multiple find/grep commands.
+
+2. **Concurrent reads** of all key files: Portal, scope specs (from SPECS list), trackers with issues (from WARNINGS). Do NOT read module specs initially — only if Check 2 needs them.
+
+3. **Do NOT run npm test.** Check 7 only verifies test FILES exist, not that they pass. Running tests is the developer's responsibility.
+
+4. **Do NOT scan code files.** Check 6 samples at most 3 files.
+
+Total: ≤5 tool calls for all 8 checks. Target: <15 seconds.
+</ExecutionStrategy>
+
+<Checks>
+Run these checks in order using BATCHED reads. Each check produces PASS / FAIL with location.
+
+### Check 1 — Portal Integrity (1 read)
+
+Read `specs/README.md`. Verify: scopes table entries match `specs/<scope>/<scope>.spec.md` existence. Graph nodes match table. Status emoji matches file presence.
+
+### Check 2 — Spec Linking (read scope specs only)
+
+For each scope spec 9/7: module paths resolve to files. Module spec 1 links to parent. Cross-scope references resolve.
+
+### Check 3 — Tracker Sync (1 grep)
+
+`grep -rn "\[x\] DONE\|\[ \] TODO\|\[~\] IN_PROGRESS\|\[!\] BLOCKED" tasks/README.md tasks/*/README.md`. Compare counts.
+
+### Check 4 — DAG Consistency (parse from tracker)
+
+Parse `Dependencies:` from each task ticket planning surface. Topological sort. No cycles.
+
+### Check 5 — Execution Log Completeness
+
+From scan [TASKS] output: check `placeholders` column for any task with >0. Flag tasks where placeholders > 0 even if status DONE. Also inspect `warnings` column for `no-execlog-section` or `anchors-mismatch`.
+
+### Check 6 — File Headers (sample 3 files)
+
+Pick 3 recently modified .ts files from `git diff --name-only HEAD~3`. Check for `@file:`, `@consumers:`, `@tasks:`.
+
+### Check 7 — Test Coverage (1 find)
+
+`find tasks -name '*.task-*.md' -type f` — for each task with kind=test phase, check Target Test Files exist.
+
+### Check 8 — Decision Log (read scope specs only)
+
+Parse D-NNN from all scope specs. Check uniqueness, supersedes links.</Checks>
+
+<Output>
+First: Self-Reflection. Then: Mechanical Checks. Use compact single-line-per-check format.
+
+```
+🔍 SDD CHECK  ·  <N> scopes  ·  <M> tasks
+
+▸ SELF-REFLECTION
+  ✅ discovery → execute         cli (TSK-12..18)
+  ✅ refine → execute             dbc content option (TSK-11)
+  ❌ code before task             TSK-19 type alias contracts
+  ❌ code before task             TSK-20 _reorderTags fix
+  ❌ no audit                     TSK-22 vcs-client
+  ⚠️  audit paperwork             TSK-11 (tracker/log gaps)
+
+▸ MECHANICAL
+  ✅ Portal          4 scopes, graph ↔ table
+  ✅ Spec linking    all modules → parent, cross-scope refs resolve
+  ✅ Tracker sync    dbc 13/13  cli 7/7  vcs 1/1
+  ✅ DAG             no cycles, all deps satisfied
+  ✅ Execution Log   no <YYYY-MM-DD> placeholders in tasks
+  ✅ File headers    21 files scanned, all have @file: + @consumers:
+  —  Test coverage   not checked
+  —  Decision Log    not checked
+
+▸ SUMMARY
+  Pass: 6/6 checks
+  Protocol: 3 violations, 1 audit missing
+
+▸ VERDICT
+  ❌ NOT READY — fix protocol violations before next execute
+```
+
+Rules for VERDICT line:
+
+- All 8 checks PASS AND 0 protocol violations → `✅ CLEAN — artifact tree is consistent, next pickable: TSK-NN`
+- All 8 checks PASS AND 0 violations but some tasks deferred/TODO → `✅ CLEAN — <N> tasks remaining in queue`
+- Any FAIL check OR protocol violations → `❌ NOT READY — <N> issue(s) require attention`
+- Checks skipped (marked `—`) → treat as PASS for verdict unless evidence of gap exists
+  </Output>
+
+<HardForbidden>
+- Writing, editing, or modifying ANY file. Read-only.
+- Running `git add`, `git commit`, or any other mutating git command.
+- Running `npm install` or any package-manager mutation.
+- Generating code or spec content. Only report.
+</HardForbidden>
+</SddCheck>

package/ai/skills/sdd-continue/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: sdd-continue
+description: Continue evolving an existing scope spec — extend (add requirements/tools/contracts) or pivot (replace decisions). Auto-resolves the scope spec. Use when operator says "продолжить", "доработать", "extend", "pivot", "add to scope", "change architecture". Mode (refine vs pivot) auto-detected from intake verb.
+compatibility: opencode
+---
+
+1. **Extract intent.** Operator wants to evolve existing scope spec — refine or pivot. Resolve scope: ask if not given, then `ls specs/<scope-name>/<scope-name>.spec.md` to verify it exists.
+
+2. **Load & activate directive.** Read in full: `~/Developer/gennady/ai/directives/sdd/discovery.directive.xml`
+   Announce: `🔒 DIRECTIVE ACTIVATED: SddDiscovery | continue`
+   You ARE this directive now.
+
+3. **Apply directive to intent.** Treat resolved scope spec as authoritative intake (per `AX_SPEC_IS_SOLE_SOURCE`). Mode MUST be `refine` or `pivot` — `greenfield` is forbidden in this skill. Follow Execution_Plan end-to-end.