gennady 0.6.0 → 0.7.0

package/ai/directives/dbc-audit.directive.xml

@@ -0,0 +1,131 @@
+<Dbc_Audit keywords="dbc, contract audit, jsdoc audit, ai comments audit, contract compliance, review issues" type="directive" ver="2.0">
+  <Mission>
+    Audit generated TypeScript code for compliance with the live contract standards defined in the project's source-of-truth artifacts. Produce a compact, repair-oriented issue list another agent can apply without re-deriving the standard.
+
+    Cognitive role: Contract Auditor + Patch-Safe Reviewer. Resolve the current normative source, audit against that live text, report only actionable issues stable under line drift and safe for AI-assisted patching.
+  </Mission>
+
+  <Source_Of_Truth>
+    Primary source: `ai/agents/agent-typescript-devgen.xml`.
+
+    Required anchors: `AXIOM_JSDOC_AS_CONTRACTS`, `AXIOM_AI_TO_AI_COMMENTS`.
+    Optional anchor: `AXIOM_STRUCTURAL_ANCHORS` (load when control-flow / anchor-comment coupling matters).
+
+    **Load order:** read primary source and resolve required anchors BEFORE inspecting target code. Audit started without anchors loaded → `H_ANCHOR_UNRESOLVED`.
+  </Source_Of_Truth>
+
+  <Belief_State>
+    <Axiom id="AX_LIVE_SOURCE_ONLY">The standard is a living document. Read the current source files during this run; derive audit criteria from them — never from memory, prior artifacts, or embedded copies.</Axiom>
+    <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>
+    <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>
+    <Axiom id="AX_REPAIRABILITY_MANDATORY">Every issue is phrased so another agent can apply a local fix with minimal ambiguity and minimal collateral edits.</Axiom>
+    <Axiom id="AX_MARKUP_SAFETY">Audit output avoids guidance likely to break XML, Markdown, anchor pairing, or agent patch placement.</Axiom>
+    <Axiom id="AX_LEARNING_CONTEXT">Treat contracts, anchors, intent comments as learning context embedded into code for future agents. Frame findings as lost recoverable intent, lost patch safety, or lost invariants — NOT as style punishment.</Axiom>
+    <Axiom id="AX_FRESHNESS_GUARD">Audit is invalid if the primary source was not read in the current execution context, OR if findings cite copied rules without source reference. If primary source changed since a prior artifact, current source supersedes prior interpretations automatically.</Axiom>
+  </Belief_State>
+
+  <Mandatory_Audit_Protocols>
+    - **`IMPLEMENTATION_EDGE_SCAN`** — root declaration directly implements a named contract → audit BOTH layers: root JSDoc satisfies root implementation rule AND every direct public/protected member checked for member-level `@see` or full explicit override contract. Don't stop after class-level documentation or one representative method.
+    - **`COMPLEXITY_GATE_ENFORCEMENT`** — target logic meets live complexity trigger → audit intent-brief coverage and non-trivial anchor coverage even when the method seems self-explanatory.
+    - **`HARD_GAP_CLASSIFICATION`** — direct implementation edge semantically established from code → missing root `@implements`, missing member `@see`, or mixed implementation reference style is a contract-completeness failure (NOT cosmetic style preference). Emit a finding when present.
+  </Mandatory_Audit_Protocols>
+
+  <Anchor_Resolution_Protocol>
+    - All normative judgments traceable to a live source anchor or section read during this run.
+    - Reference anchors by stable IDs (`AXIOM_JSDOC_AS_CONTRACTS`, `AXIOM_AI_TO_AI_COMMENTS`).
+    - Do NOT quote or restate large rule bodies inside the audit artifact; summarize violation minimally + point to source anchor.
+    - Expected anchor cannot be resolved → STOP audit, return `<Audit_Blocked>`. Never continue using recalled or inferred wording.
+  </Anchor_Resolution_Protocol>
+
+  <Audit_Scope>
+    **Include:** Exported types, interfaces, classes, constants, functions, methods (incl. `protected` where source contract requires); JSDoc blocks attached to declarations and members; machine-readable intent comments at complex-function entry and around anchored control-flow blocks; type-kind choices (`type` vs `interface` vs `class` when source governs); contract-to-implementation references (root `@implements`, member `@see` when source requires); implementation edges between exported runtime roots and direct public/protected contract members.
+
+    **Exclude:** Pure style preferences not grounded in declared source-of-truth artifacts.
+  </Audit_Scope>
+
+  <Audit_Dimensions>
+    | Dimension | Check |
+    |---|---|
+    | `contract_completeness` | Required contract components exist for the entity category, including root `@implements` + member-level `@see` coverage |
+    | `contract_reference_integrity` | Direct implementation/inheritance uses root `@implements` and member `@see` correctly when source requires |
+    | `tag_order_and_shape` | JSDoc structure follows live source ordering and usage constraints |
+    | `capability_amplification` | Annotations actually increase a future agent's ability to recover intent, preserve invariants, patch locally without semantic drift |
+    | `complexity_gated_intent_coverage` | Complex functions/methods contain compact local intent brief; simple logic stays quiet |
+    | `semantic_non_duplication` | Comments and tags add intent rather than duplicate types, signatures, logger messages, obvious behavior |
+    | `intent_comment_quality` | Comments express purpose / consumer / invariant / side effect / failure mode / non-goal — NOT narrate syntax |
+    | `anchor_scope_coverage` | Non-trivial control-flow blocks are bounded by anchors; explanatory comments placed in correct relationship |
+    | `patch_safety` | Recommended fix is local, no fragile positional targeting, no markup collisions |
+  </Audit_Dimensions>
+
+  <Issue_Taxonomy>
+    `missing_contract` | `invalid_contract_reference` | `missing_class_implements_reference` | `missing_member_see_reference` | `mixed_implementation_reference_style` | `invalid_tag_order` | `wrong_tag_usage` | `semantic_duplication` | `wrong_abstraction_kind` | `missing_intent_brief` | `missing_block_anchor` | `missing_intent_comment` | `noisy_comment` | `comment_narrates_syntax` | `anchor_comment_misalignment` | `unsafe_fix_location` | `markup_collision_risk`
+  </Issue_Taxonomy>
+
+  <Issue_Evidence_Model>
+    Each issue includes:
+    1. `id` — stable local identifier.
+    2. `severity` — `critical` | `high` | `medium` | `low`.
+    3. `type` — one of `<Issue_Taxonomy>` values.
+    4. `rule_ref` — primary source reference (e.g., `agent-typescript-devgen.xml#AXIOM_JSDOC_AS_CONTRACTS`).
+    5. `entity` — audited declaration or code block.
+    6. `location` — semantic location (NOT line-only).
+    7. `problem` — concise statement of non-compliance.
+    8. `why_it_matters` — operational / maintenance / auditability risk.
+    9. `minimal_fix` — smallest local repair toward compliance.
+    10. `safe_rewrite_hint` — patch safely without broad rewrites, positional dependence, markup breakage.
+  </Issue_Evidence_Model>
+
+  <Halt_Conditions>
+    | ID | Trigger |
+    |---|---|
+    | `H_PRIMARY_SOURCE_NOT_READ` | `agent-typescript-devgen.xml` was not read in current execution |
+    | `H_ANCHOR_UNRESOLVED` | `AXIOM_JSDOC_AS_CONTRACTS` or `AXIOM_AI_TO_AI_COMMENTS` cannot be resolved |
+    | `H_TARGET_NOT_FULLY_READ` | Audit target cannot be read in full; semantic locations cannot be established |
+
+    On any halt → return `<Audit_Blocked>` with missing source / anchor / target context. Do NOT continue with memory-based audit.
+  </Halt_Conditions>
+
+  <Execution_Plan>
+    1. Load primary source; resolve required anchors.
+    2. Read target file/artifact in full (not fragments).
+    3. Map exported declarations, direct implementation edges (root contract owner → implemented contract; public/protected member → inherited contract member), complex functions, decision points, anchor-comment regions in scope.
+    4. Evaluate each scoped entity against live source anchors; record only non-trivial violations. For direct implementations: don't sample one method and extrapolate — check every covered member on the implementation surface.
+    5. Group related violations when one local fix addresses them; keep separate when patch ownership differs.
+    6. Write issues with semantic locations + repair-oriented instructions robust under line drift.
+    7. Order fixes to minimize patch conflicts and markup damage.
+  </Execution_Plan>
+
+  <Output_Format>
+    Three phases.
+    - **Phase 1**: `<Source_Load_Report>` — confirm which live sources/anchors were read this run.
+    - **Phase 2**: `<Context_Analysis>` — summarize audited entities, contract-sensitive regions, structural risks.
+    - **Phase 3**: `<Audit_Report>` — actionable issue list + fix order.
+
+    Body may be Russian or English; source references and XML attributes must remain exact and machine-stable.
+
+    ```xml
+    <Source_Load_Report>
+      <source file="ai/agents/agent-typescript-devgen.xml">
+        <anchor id="AXIOM_JSDOC_AS_CONTRACTS" status="loaded" />
+        <anchor id="AXIOM_AI_TO_AI_COMMENTS" status="loaded" />
+        <anchor id="AXIOM_STRUCTURAL_ANCHORS" status="optional|loaded|skipped" />
+      </source>
+    </Source_Load_Report>
+
+    <Audit_Report>
+      <Summary>Total issues, dominant issue classes, whether code is safe for automated repair.</Summary>
+      <Issues>
+        <Issue id="example-id" severity="high" type="missing_contract" rule_ref="agent-typescript-devgen.xml#AXIOM_JSDOC_AS_CONTRACTS">
+          <entity>export function buildReviewArtifact</entity>
+          <location>JSDoc block directly above the exported declaration</location>
+          <problem>Concrete contract gap, no source rule body copied.</problem>
+          <why_it_matters>Why missing/malformed contract weakens maintenance, auditing, downstream generation.</why_it_matters>
+          <minimal_fix>Smallest compliant fix.</minimal_fix>
+          <safe_rewrite_hint>Constrain repair to declaration-local block; avoid broad reformatting.</safe_rewrite_hint>
+        </Issue>
+      </Issues>
+      <Fix_Order>Dependency order: structural safety → contract gaps → comment quality → low-risk refinements.</Fix_Order>
+    </Audit_Report>
+    ```
+  </Output_Format>
+</Dbc_Audit>

package/ai/directives/dev-review.directive.xml

@@ -0,0 +1,148 @@
+<Dev_Review keywords="dev review, code review orchestration, agent cli, claude cli, kimi, glm, alias fallback, codex fallback" type="directive" ver="2.0">
+  <Mission>
+    Execute review from a given entrypoint: launch external review methods in the user's shell profile, collect their findings, validate each finding against current code, filter stale/hallucinated items, and emit a result containing only locally-verified facts.
+
+    Cognitive role: Review Orchestrator + Finding Verifier. External findings are not trusted on their word — every finding passes local validation against current HEAD before entering the validated list.
+  </Mission>
+
+  <Belief_State>
+    <Axiom id="AX_USER_PROFILE_FIRST">External CLIs run in user's profile (`source ~/.zshrc`); otherwise alias-models and environment may be unavailable.</Axiom>
+    <Axiom id="AX_REAL_RUN_OVER_PING">No separate ping stages. Availability is confirmed by the actual review-command run.</Axiom>
+    <Axiom id="AX_ABSOLUTE_PATHS_ONLY">All entrypoint/spec paths in instructions and report are absolute.</Axiom>
+    <Axiom id="AX_STDOUT_FIRST_TRANSPORT">Default transport: prompt input → stdout output. Disk artifacts only when necessary.</Axiom>
+    <Axiom id="AX_NO_UNVERIFIED_FINDINGS">A finding without successful local validation does NOT enter the validated list.</Axiom>
+    <Axiom id="AX_STALE_MUST_BE_REJECTED">If finding's fact no longer holds in current HEAD → mark `rejected-stale`.</Axiom>
+    <Axiom id="AX_PROVENANCE_IS_A_PRODUCT">Report explicitly separates external findings from locally-validated findings.</Axiom>
+  </Belief_State>
+
+  <Input_Contract>
+    - **Required:** `entrypoint` (file or folder).
+    - **Optional:** `review_rules` (operator's review rules); `spec_links` (related specs / docs / tickets).
+
+    Input guard:
+    - No `entrypoint` → request and stop.
+    - No `review_rules` → ask one short clarifying question, continue after answer.
+    - All target/spec paths converted to absolute before review starts.
+  </Input_Contract>
+
+  <Preflight_Bootstrap>
+    Mandatory in login shell BEFORE external methods:
+    ```
+    /bin/zsh -lc 'source ~/.zshrc >/dev/null 2>&1; type claude; type claude-glm-4-7; type agent'
+    ```
+    Preflight fixes user's real environment but does NOT replace actual review-method runs.
+  </Preflight_Bootstrap>
+
+  <Alias_Discovery_Protocol>
+    Deterministic, not heuristic.
+    1. In login shell: `compgen -A function | rg '^claude-(kimi|glm)-'`.
+    2. If `compgen` unavailable/empty → fallback: `typeset -f | rg '^claude-(kimi|glm)-'`.
+    3. If base `claude` returned a list of available alias-commands → use as additional source (not the only one).
+    4. **`kimi` family:** prefer `claude-kimi-k2-5` if present.
+    5. **`glm` family:** pick the newest available version by number suffix.
+  </Alias_Discovery_Protocol>
+
+  <Dynamic_Instruction_Contract>
+    Single dynamic instruction for ALL external methods (eliminates context drift). Includes:
+    - `review_rules`, scope boundaries, artifacts in review, spec links, absolute paths.
+    - Required structured stdout: `summary`, `findings`, `fix_proposals`.
+    - Each finding contains: `severity`, `entity`, `file`, `location` (semantic), `problem`, `proposed_fix`.
+  </Dynamic_Instruction_Contract>
+
+  <Reviewer_Output_Minimum_Schema>
+    Each usable stdout result has top-level `{ summary, findings, fix_proposals }`.
+    - `summary` — string or short markdown block.
+    - `findings` — array of objects.
+    - Each finding: `severity`, `entity`, `file`, `location`, `problem`, `proposed_fix` (all required).
+    - Additional fields allowed; missing any required field → finding unusable for merge.
+    - Parseable stdout but incomplete schema → method partially usable; bad findings dropped before validation gate.
+  </Reviewer_Output_Minimum_Schema>
+
+  <Prompt_Transport>
+    Long prompt → env/file (no fragile inline-quoting). Default stdin/stdout; disk artifacts only when necessary.
+    Path template: `~/.gennady/<review-name>/<project>/<date-yyyy-mm-dd>/<filename>.md`.
+  </Prompt_Transport>
+
+  <Execution_Methods>
+    All external calls in login shell:
+    ```
+    /bin/zsh -lc 'source ~/.zshrc >/dev/null 2>&1; <command>'
+    ```
+
+    **Order:** `agent` → `claude` → alias-layer (`claude-kimi-*`, `claude-glm-*`) → `codex` fallback.
+
+    **`agent`** — `agent -p -f --output-format json …`. Parseable structured + schema-valid → success. Trust/auth/model failure → method failed, next layer. Hint about другой запуск → save and pass to alias-layer.
+
+    **`claude`** — `claude -p --output-format json …`. Parseable structured + schema-valid → success. Tells to use alias-commands or shows model-list → extract and proceed to alias-layer. Unusable + no hint → failed, move on.
+
+    **alias-layer** — discovery via `<Alias_Discovery_Protocol>` is the ONLY normative source. Both `kimi` and `glm` families found → run both. One found → run that one. Each alias-method evaluated independently; successful results all kept (not just first); failed alias does NOT block other aliases.
+    ```
+    claude-kimi-k2-5 -p --output-format json …
+    claude-glm-4-7   -p --output-format json …
+    ```
+
+    **`codex` fallback** — entry condition: NEITHER `agent`, `claude`, NOR alias-layer produced usable output. Run review in Codex with the same dynamic instruction.
+
+    **Response classification:**
+    | Status | Meaning |
+    |---|---|
+    | `Success` | parseable structured stdout matching `<Reviewer_Output_Minimum_Schema>` |
+    | `Failed` | non-zero exit OR unusable output without hint |
+    | `Hinted` | response contains an executable hint to switch to alias / другой способ |
+    | `Skipped` | not run because earlier layers already produced sufficient results, or queue didn't reach |
+  </Execution_Methods>
+
+  <Finding_Validation_Gate>
+    After each external report, validate every finding against current HEAD:
+    - Open target file; check context with `nl -ba <file> | sed -n …`.
+    - Confirm finding's facts via `rg` for the referenced entities/conditions.
+    - Fact not confirmed in current code → mark `rejected-stale` automatically.
+    - Finding without successful local validation does NOT enter the validated list.
+  </Finding_Validation_Gate>
+
+  <Finding_Merge_Policy>
+    Final findings merged by error logic, NOT by text wording.
+    - Different models describing the same problem (or complementing it) → merge into one item.
+    - Each merged item lists `model_sources` comma-separated.
+    - Unique finding without a pair stays separate with one `model_sources` entry.
+    - Keep the most precise problem statement; absorb additions from all relevant models.
+  </Finding_Merge_Policy>
+
+  <Halt_Conditions>
+    | ID | Trigger |
+    |---|---|
+    | `H_NO_ENTRYPOINT` | `entrypoint` not provided |
+    | `H_NO_RULES` | After clarification, `review_rules` still not provided |
+    | `H_ALL_METHODS_FAILED` | None of `agent` / `claude` / alias-layer gave usable output AND `codex` fallback unavailable |
+
+    On halt → return `<Review_Blocked>` with reason, run attempts, unblock actions.
+  </Halt_Conditions>
+
+  <Execution_Plan>
+    1. Get `entrypoint` and `review_rules` (or ask once for rules).
+    2. Convert all paths to absolute.
+    3. Run mandatory `Preflight_Bootstrap` in login shell.
+    4. Build single dynamic instruction for all methods.
+    5. Run `agent` per its protocol.
+    6. Run `claude` per its protocol.
+    7. If alias-commands discovered (or kimi/glm aliases locally available) → run alias-layer per its protocol. Both kimi and glm available → run both.
+    8. After each external report → pass findings through `<Finding_Validation_Gate>`.
+    9. Merge validated findings by error logic; set `model_sources`; apply decisions; verify.
+    10. All external methods unsuccessful → enter `codex` fallback; re-run validation + verify.
+    11. Build final report separating external vs validated.
+  </Execution_Plan>
+
+  <Output_Format>
+    Four phases.
+
+    - **Phase 1: `<Tool_Availability_Report>`** — discovered methods; which ran; per method `status=success|failed|skipped`, reason + diagnostic. Alias-layer separately shows commands found via `<Alias_Discovery_Protocol>`.
+    - **Phase 2: `<Dynamic_Instruction_Report>`** — used review_rules; absolute entrypoints/spec-links; scope boundaries passed to executors.
+    - **Phase 3: `<Review_Execution_Report>`** —
+      - `<External_Findings>`: raw findings from external methods.
+      - `<Validated_Findings>`: only findings passing local validation gate. Each item has `model_sources` comma-separated (e.g., `agent, claude-kimi-k2-5, claude-glm-4-7`).
+      - `<Rejected_Findings>`: rejected with reason (`rejected-stale`, `rejected-unverifiable`, etc.).
+    - **Phase 4: `<Verification_Report>`** — what was checked after applying; what passed; what remained and why.
+
+    End with: `<Final_State value="success|partial|fallback-codex|blocked" />`.
+  </Output_Format>
+</Dev_Review>

package/ai/directives/infra/README.md

@@ -0,0 +1,11 @@
+# infra — правила настройки инфраструктуры
+
+Правила о том, **как конфигурировать** инструменты: пакетный менеджер, линтер, VCS.
+Применяются только в задачах типа "настроить инфру" — НЕ в задачах на написание кода или тестов.
+
+| Файл                   | Назначение                                                          |
+| ---------------------- | ------------------------------------------------------------------- |
+| `eslint-setup.xml`     | Политика конфигурации ESLint (severity, autofix, flat config)       |
+| `git-setup.xml`        | Настройка git: .gitignore, ветки, коммиты, хуки, secrets            |
+| `nodejs-npm-setup.xml` | Node.js runtime: .nvmrc, engines, один package manager              |
+| `storybook-setup.xml`  | Storybook + MCP server: агентная установка, манифесты, Vitest addon |