gennady 0.8.3 → 0.8.4-draft.2

package/dist/shared/sdd/ticket.d.ts

@@ -0,0 +1,81 @@
+/** @purpose One Spec Reference entry from Meta. */
+export type SpecRef = {
+    /** @purpose Role label (Contract / Adapter / Consumer / …), or empty if the bullet had none. */
+    role: string;
+    /** @purpose Linked entity name (the link text). */
+    name: string;
+    /** @purpose Link target (spec anchor / path). */
+    anchor: string;
+};
+/** @purpose Parsed Meta planning fields of a ticket. */
+export type MetaInfo = {
+    /** @purpose Task-ID (`<ACR>-<slug>`) or null. */
+    taskId: string | null;
+    /** @purpose Status token (e.g. `[x] DONE`) or null. */
+    status: string | null;
+    /** @purpose One-line purpose, or null. */
+    purpose: string | null;
+    /** @purpose Owning scope, or null. */
+    scope: string | null;
+    /** @purpose Owning module, or null. */
+    module: string | null;
+    /** @purpose Dependency Task-IDs (empty when None). */
+    dependencies: string[];
+    /** @purpose Spec References — the enumerable contract set. */
+    specRefs: SpecRef[];
+};
+/** @purpose One row of the Phases Overview table. */
+export type PhaseOverview = {
+    /** @purpose Phase id (e.g. P1). */
+    id: string;
+    /** @purpose Phase kind (bootstrap/impl/test/config/doc/refactor). */
+    kind: string;
+    /** @purpose Phase dependency ids (empty when —). */
+    deps: string[];
+    /** @purpose Status flag cell (e.g. `[ ]`). */
+    status: string;
+};
+/** @purpose Parsed body of one phase section. */
+export type PhaseDetail = {
+    /** @purpose One-line objective, or null. */
+    objective: string | null;
+    /** @purpose Rule links (markdown link targets) the phase activates. */
+    rules: string[];
+    /** @purpose Target file paths the phase may write. */
+    targetFiles: string[];
+    /** @purpose Inputs line (e.g. `none`, `P1 handoff`), or null. */
+    inputs: string | null;
+    /** @purpose Exit criterion, or null. */
+    exit: string | null;
+};
+/** @purpose One Verification gate row. */
+export type Gate = {
+    /** @purpose The resolved check command. */
+    command: string;
+    /** @purpose Rule-ids that require this gate. */
+    requiredBy: string[];
+};
+/**
+ * @purpose Parse the planning fields of a ticket Meta section.
+ * @param metaBody Text between the META markers.
+ * @returns A MetaInfo; absent fields are null / empty.
+ */
+export declare function parseMetaInfo(metaBody: string): MetaInfo;
+/**
+ * @purpose Parse the Phases Overview table.
+ * @param body Text of the PHASES_OVERVIEW section.
+ * @returns One PhaseOverview per data row.
+ */
+export declare function parsePhasesOverview(body: string): PhaseOverview[];
+/**
+ * @purpose Parse one phase section body into its planning fields.
+ * @param phaseBody Text between a PHASE_P<n> marker pair.
+ * @returns The PhaseDetail (objective, rule links, target files, inputs, exit).
+ */
+export declare function parsePhaseDetail(phaseBody: string): PhaseDetail;
+/**
+ * @purpose Parse the Verification gate table.
+ * @param body Text of the VERIFICATION section.
+ * @returns One Gate per command row.
+ */
+export declare function parseVerification(body: string): Gate[];

package/dist/shared/sdd/tracker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @purpose Task-ID and Status read from a ticket Meta section.
+ * @invariant Either field is null when its Meta line is absent or unparseable.
+ */
+export type TicketMeta = {
+    /** @purpose Task-ID (`<ACR>-<slug>`) from the Meta section, or null if absent. */
+    taskId: string | null;
+    /** @purpose Status token (e.g. `[x] DONE`) from the Meta section, or null if absent. */
+    status: string | null;
+};
+/**
+ * @purpose Outcome of a tracker Status-cell update.
+ * @invariant `ok` carries the (possibly unchanged) text and whether a byte changed; failures name why no row was touched.
+ */
+export type TrackerUpdate = {
+    ok: true;
+    text: string;
+    changed: boolean;
+} | {
+    ok: false;
+    reason: 'no_table' | 'task_not_found';
+};
+/**
+ * @purpose Extract Task-ID and Status from a ticket Meta section body.
+ * @invariant Tolerant of both v2 bold (`**Task-ID:**`) and unmarked v1 (`- Task-ID:`) Meta lines — a
+ *   v1 ticket must never silently parse as null.
+ * @param metaBody The text between the META markers.
+ * @returns TicketMeta with each field parsed or null.
+ */
+export declare function parseMeta(metaBody: string): TicketMeta;
+/**
+ * @purpose Surgically set the Status cell of the tracker row whose Task-ID matches, leaving other cells byte-identical.
+ * @invariant Locates columns by header (`Task-ID` / `Status`) — never by fixed index, since module vs scope trackers differ.
+ * @invariant Only the matched row's Status segment is rewritten; all other rows and cells are untouched.
+ * @param content Full markdown of an index file.
+ * @param taskId Task-ID to match (compared against the link/backtick-stripped cell).
+ * @param newStatus Status token to write (e.g. `[x] DONE`).
+ * @returns ok with the updated text and whether it changed, or a failure reason (no tracker table / row not found).
+ */
+export declare function updateTrackerStatus(content: string, taskId: string, newStatus: string): TrackerUpdate;
+/** @purpose One Tracker-Index row reduced to the fields the cross-check needs. */
+export type TrackerRow = {
+    /** @purpose Task-ID from the row's Task-ID cell (link/backtick-stripped). */
+    taskId: string;
+    /** @purpose Status cell text (e.g. `[x] DONE`), whitespace-trimmed. */
+    status: string;
+};
+/**
+ * @purpose Read the Tracker-Index rows of an index file — the read-only counterpart to updateTrackerStatus.
+ * @param content Full markdown of a `*.3-tasks.md` index file.
+ * @returns One TrackerRow per data row; empty when the file has no Task-ID/Status table.
+ */
+export declare function parseTrackerRows(content: string): TrackerRow[];
+/**
+ * @purpose True when a TrackerRow's Status cell is a `[x]` checkbox (case-insensitive) — done.
+ * @param status The Status cell text.
+ * @returns Whether the row is done.
+ */
+export declare function isRowDone(status: string): boolean;
+/**
+ * @purpose Recompute a rollup table's Tasks/Done cells from each row's linked tracker file.
+ * @invariant A non-rollup table, or a row with no link / an unresolvable target, stays byte-identical.
+ * @param content Full markdown of the rollup file (e.g. `specs/3-tasks.md`, or a scope's `*.3-tasks.md`).
+ * @param resolveRows For an Index-cell link target, that tracker's rows, or null if unreadable.
+ * @returns The rewritten content, plus the link target of every row whose cells changed.
+ */
+export declare function recomputeRollupProgress(content: string, resolveRows: (indexLink: string) => TrackerRow[] | null): {
+    text: string;
+    updated: string[];
+};

package/dist/shared/sdd/yagni.d.ts

@@ -0,0 +1,71 @@
+/** @purpose One symbol added or modified by the diff under check. */
+export type ChangedSymbol = {
+    /** @purpose Symbol name. */
+    name: string;
+    /** @purpose Declaration kind (informational — see DeclaredSymbol.kind). */
+    kind: string;
+    /** @purpose File the symbol was declared in. */
+    file: string;
+};
+/** @purpose A parsed `- **Usage Waiver:** <reason>` (or `D-NNN — <reason>`, or the `(external: <consumer>)` variant). */
+export type UsageWaiver = {
+    /** @purpose Cited Decision Log id, e.g. `D-042` — present only when the label cites one; a waiver without a citation still gates. */
+    decision?: string;
+    /** @purpose Waiver reason text. */
+    reason: string;
+    /** @purpose Named external consumer, for the public-API waiver variant — undefined otherwise. */
+    external?: string;
+};
+/** @purpose One YAGNI finding, ESLint-shaped like `gennady lint`'s LintError. */
+export type YagniFinding = {
+    /** @purpose Always 'error' — an ungated underused symbol blocks the gate (D-YG004: strict for all entities, diff scope has no legacy). */
+    severity: 'error';
+    /** @purpose ERR_CLI_YAGNI_* code. */
+    code: string;
+    /** @purpose File the finding refers to. */
+    file: string;
+    /** @purpose The symbol name the finding is about. */
+    symbol: string;
+    /** @purpose Description with the issue and the fix. */
+    message: string;
+};
+/** @purpose Symbol has < 2 production-code usages and no Usage Waiver gates it. */
+export declare const ERR_CLI_YAGNI_UNDERUSED: "ERR_CLI_YAGNI_UNDERUSED";
+/** @purpose Symbol has a Usage Waiver, but the cited D-NNN has no Decision Log heading anywhere in the repo. */
+export declare const ERR_CLI_YAGNI_WAIVER_DECISION_MISSING: "ERR_CLI_YAGNI_WAIVER_DECISION_MISSING";
+/**
+ * @purpose Strip barrel re-export lines (`export { X } from '...'` / `export * from '...'`) —
+ *   a re-export is not a usage.
+ * @param content Source text.
+ * @returns `content` with every top-level re-export line blanked out (line count preserved).
+ */
+export declare function stripBarrelReexports(content: string): string;
+/**
+ * @purpose Parse a `Usage Waiver` line inside one entity's heading, gated to a contract/surface
+ *   section (`WAIVER_SECTIONS`) — never a Decision Log entry.
+ * @param specContent Full markdown content of one spec/contract file.
+ * @param entityName The entity heading to look inside — bare-name (``### `<entityName>` ``, any
+ *   level) or DbC port/adapter/service (``#### Port: `<entityName>` ``, optionally numbered).
+ * @returns The parsed waiver, or null when the entity has no in-scope heading or no Usage Waiver line, or the reason is empty.
+ */
+export declare function parseUsageWaiver(specContent: string, entityName: string): UsageWaiver | null;
+/**
+ * @purpose Whether a Decision Log heading for `decisionId` exists anywhere in `content` (``### D-NNN — ...``).
+ * @param content Markdown content to search.
+ * @param decisionId Decision id, e.g. `D-042`.
+ * @returns True when a matching heading is found.
+ */
+export declare function hasDecisionHeading(content: string, decisionId: string): boolean;
+/**
+ * @purpose YAGNI usage check — an underused symbol is a finding unless a Usage Waiver gates it.
+ * @invariant Tests never count as usage — callers exclude test files from `usageCounts`.
+ * @invariant A waiver with no `D-NNN` citation gates unconditionally — the reason alone is enough.
+ * @invariant An unresolvable `D-NNN` citation does NOT gate the finding — it downgrades to a more
+ *   specific finding instead of silently passing.
+ * @param changed Symbols added/modified in the diff.
+ * @param usageCounts Symbol name → usage count in production code across the whole repo (the symbol's own declaration occurrence already excluded).
+ * @param waivers Symbol name → parsed Usage Waiver, when its contract declares one.
+ * @param liveDecisions Decision ids confirmed to have a Decision Log heading somewhere in the repo.
+ * @returns One finding per underused, ungated symbol.
+ */
+export declare function checkYagniUsage(changed: ChangedSymbol[], usageCounts: Map<string, number>, waivers: Map<string, UsageWaiver>, liveDecisions: Set<string>): YagniFinding[];

package/dist/utils/test/mock-http.d.ts

@@ -0,0 +1,51 @@
+import { MockAgent } from 'undici';
+/** A single mocked response. `body` as object is JSON-encoded; as string is sent verbatim. */
+export interface MockReply {
+    status: number;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** The intercepted request, handed to a reply function for param-aware ("intelligent") answers. */
+export interface InterceptedRequest {
+    method: string;
+    /** Full path including query string, e.g. `/api/v4/mrs?state=opened`. */
+    path: string;
+    /** Parsed query params of `path` for convenient dispatch. */
+    query: URLSearchParams;
+    headers: Record<string, string | string[] | undefined>;
+    /** Raw request body as a string (JSON not parsed) or null when absent. */
+    body: string | null;
+}
+/**
+ * A reply that inspects the request — the seam for an intelligent mock backend.
+ * Synchronous by undici's contract; load any fixture data before registering the intercept.
+ */
+export type ReplyFn = (req: InterceptedRequest) => MockReply;
+/** Reports how many times the registered endpoint was actually hit. */
+export interface AttemptTracker {
+    getAttemptCount(): number;
+}
+export interface MockHttpEnv {
+    /** Intercept one matching call; `reply` may be static or a request-inspecting function. */
+    interceptOnce(method: string, url: string, reply: MockReply | ReplyFn): AttemptTracker;
+    /** Intercept N sequential calls to the same endpoint, one reply per attempt in order. */
+    interceptMultiple(method: string, url: string, replies: Array<MockReply | ReplyFn>): AttemptTracker;
+    /** Restore the previous global dispatcher. Call in `afterEach`. */
+    cleanup(): void;
+    /** The underlying MockAgent, for advanced assertions (e.g. assertNoPendingInterceptors). */
+    agent: MockAgent;
+}
+interface SetupOptions {
+    /**
+     * Net-connect policy for un-intercepted requests.
+     * `false` (default) — throw on any real network call (strict black-box).
+     * `true` — allow all real connections. A string/RegExp — allow only matching hosts.
+     */
+    allowNetConnect?: boolean | string | RegExp;
+}
+/**
+ * Install a MockAgent as the global dispatcher so `fetch()` (and any undici-based client,
+ * including the OpenCode SDK default fetch and the GitLab client) is intercepted transparently.
+ */
+export declare function setupMockAgent(opts?: SetupOptions): MockHttpEnv;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gennady",
-  "version": "0.8.3",
+  "version": "0.8.4-draft.2",
   "author": "Konstantin Lebedev <ibnrubaxa@gmail.com>",
   "description": "Gennady — General Extensible Neural Network Adaptive Data Yntelligence",
   "keywords": [
@@ -22,7 +22,8 @@
   "types": "dist/index.d.ts",
   "imports": {
     "#snapshot-path-setup": "./snapshot-path.setup.ts",
-    "#logger": "./services/logger/logger.ts"
+    "#logger": "./services/logger/logger.ts",
+    "#utils/*": "./utils/*"
   },
   "exports": {
     ".": "./services/agent-mon/index.ts",
@@ -36,44 +37,80 @@
     "cli/cmd/orient/README.md"
   ],
   "scripts": {
+    "prepare": "[ -d .git ] && git config core.hooksPath scripts/git-hooks || true",
     "type-check": "tsc --noEmit",
     "build:types": "tsc -p tsconfig.types.json && node --import tsx scripts/normalize-dts-imports.ts",
     "build:publish": "npm run build && npm run build:types && node --import tsx scripts/prepare-publish-artifacts.ts",
-    "test": "node --import tsx --test --experimental-test-module-mocks",
+    "test": "node --import tsx --test --experimental-test-module-mocks $(find ai cli shared services -name '*.test.ts' -not -path '*/serve/__tests__/*' -not -name '*.integration.test.ts' -not -name '*.real-integration.test.ts' -not -name 'http-server.test.ts' -not -name 'eval-driver.test.ts' -not -name 'reviewer.e2e.test.ts' -not -name 'full-flow.blackbox.test.ts' -not -name 'run-mode.test.ts')",
+    "test:coverage": "node --test --import tsx --experimental-test-module-mocks $(find ai cli shared services -name '*.test.ts' -not -path '*/serve/__tests__/*' -not -name '*.integration.test.ts' -not -name '*.real-integration.test.ts' -not -name 'http-server.test.ts' -not -name 'eval-driver.test.ts' -not -name 'reviewer.e2e.test.ts' -not -name 'full-flow.blackbox.test.ts' -not -name 'run-mode.test.ts')",
     "test:e2e": "GENNADY_E2E=1 node --import tsx --test --experimental-test-module-mocks cli/__tests__/e2e/*.test.ts",
+    "test:integration": "node --import tsx --test --experimental-test-module-mocks --test-concurrency=2 services/agent-inbox/serve/__tests__/*.test.ts services/agent-inbox/modules/*/__tests__/*.integration.test.ts services/agent-inbox/modules/inbox-api/__tests__/http-server.test.ts services/agent-inbox/modules/inbox-roles/__tests__/reviewer.e2e.test.ts services/agent-inbox/modules/inbox-eval/__tests__/eval-driver.test.ts services/mr-stats/__tests__/*.integration.test.ts",
     "test:watch": "tsx --test-loader 'cli/**/*.test.ts' 'shared/**/*.test.ts' 'services/**/*.test.ts'",
     "dev": "tsx cli/gennady.ts",
+    "inspector": "tsx ai/inspector/generate.ts && tsx ai/inspector/serve.ts",
+    "inspector:gen": "tsx ai/inspector/generate.ts",
+    "inspector:serve": "tsx ai/inspector/serve.ts",
+    "inspector:test": "node --import tsx --test ai/inspector/core/__tests__/*.test.ts ai/inspector/web/__tests__/*.test.ts",
+    "inbox-serve:dev": "vite --config services/agent-inbox/modules/inbox-dashboard/vite.config.ts",
+    "inbox-serve:build": "vite build --config services/agent-inbox/modules/inbox-dashboard/vite.config.ts",
+    "inspector:e2e": "playwright test --config=ai/inspector/playwright.config.ts",
+    "test:e2e:review-flow": "playwright test --config=e2e/inbox-serve/playwright.review-flow.config.ts",
     "build": "vite build",
     "prepublishOnly": "npm run lint && npm run test:e2e && npm run build:publish",
     "postpublish": "node --import tsx scripts/cleanup-publish-artifacts.ts",
     "publish-next": "node --import tsx scripts/publish-next.ts",
+    "publish-draft": "node --import tsx scripts/publish-draft.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "npm run format && npm run type-check && npm run lint:contracts",
     "release": "release-it",
-    "lint:contracts": "tsx cli/gennady.ts lint --autofix cli/ shared/ services/"
+    "lint:contracts": "tsx cli/gennady.ts lint --autofix cli/ shared/ services/",
+    "yagni": "tsx cli/gennady.ts yagni"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.41",
+    "@fontsource/geist": "5.3.0",
+    "@fontsource/jetbrains-mono": "5.3.0",
     "@mtcute/dispatcher": "^0.29.0",
     "@mtcute/node": "^0.28.2",
+    "@opencode-ai/sdk": "^1.17.18",
+    "@playwright/cli": "^0.1.17",
+    "@playwright/test": "^1.61.1",
+    "@tailwindcss/typography": "^0.5.20",
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/jsdom": "^28.0.3",
     "@types/node": "^25.3.2",
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
     "ai": "^6.0.116",
+    "c8": "^12.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
     "fast-glob": "^3.3.3",
+    "grammy": "^1.45.1",
+    "handlebars": "^4.7.9",
+    "lucide-react": "^1.24.0",
+    "marked": "^18.0.6",
     "open": "^11.0.0",
     "prettier": "^3.4.2",
     "qrcode": "^1.5.4",
     "release-it": "20.0.1",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
     "tsx": "^4.19.1",
     "typescript": "^5.7.2",
     "vite": "^6.0.0",
     "zod": "^4.3.6"
   },
   "dependencies": {
+    "dompurify": "^3.4.12",
     "ink": "^7.0.3",
-    "react": "^19.2.6",
+    "jsdom": "^29.1.1",
+    "mermaid": "^11.16.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "tree-sitter": "^0.22.4",
     "tree-sitter-typescript": "^0.23.2"
   }

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

@@ -1,131 +0,0 @@
-<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>