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.
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`.
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.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.Findings use stable semantic locations (declaration name, JSDoc block, anchor, method, branch). Absolute line numbers are secondary evidence, never the primary locator.Every issue is phrased so another agent can apply a local fix with minimal ambiguity and minimal collateral edits.Audit output avoids guidance likely to break XML, Markdown, anchor pairing, or agent patch placement.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.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.
- **`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.
- 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 ``. Never continue using recalled or inferred wording.
**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.
| 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 |
`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`
Each issue includes:
1. `id` — stable local identifier.
2. `severity` — `critical` | `high` | `medium` | `low`.
3. `type` — one of `` 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.
| 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 `` with missing source / anchor / target context. Do NOT continue with memory-based audit.
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.
Three phases.
- **Phase 1**: `` — confirm which live sources/anchors were read this run.
- **Phase 2**: `` — summarize audited entities, contract-sensitive regions, structural risks.
- **Phase 3**: `` — actionable issue list + fix order.
Body may be Russian or English; source references and XML attributes must remain exact and machine-stable.
```xml
Total issues, dominant issue classes, whether code is safe for automated repair.export function buildReviewArtifactJSDoc block directly above the exported declarationConcrete contract gap, no source rule body copied.Why missing/malformed contract weakens maintenance, auditing, downstream generation.Smallest compliant fix.Constrain repair to declaration-local block; avoid broad reformatting.Dependency order: structural safety → contract gaps → comment quality → low-risk refinements.
```