---
description: Maintain semantic integrity by generating maps and auditing compliance reports.
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Goal

Ensure the codebase adheres to the semantic standards defined in `.ai/standards/semantics.md` by using the AXIOM MCP semantic graph as the primary execution engine. This involves reindexing the workspace, measuring semantic health, auditing contract compliance, auditing decision-memory continuity, and optionally delegating contract-safe fixes through MCP-aware agents.

## Operating Constraints

1. **ROLE: Orchestrator**: You are responsible for the high-level coordination of semantic maintenance.
2. **MCP-FIRST**: Use the connected AXIOM MCP server as the default mechanism for discovery, health checks, audit, semantic context, impact analysis, and contract mutation planning.
3. **STRICT ADHERENCE**: Follow `.ai/standards/semantics.md` for all anchor and tag syntax.
4. **NON-DESTRUCTIVE**: Do not remove existing code logic; only add or update semantic annotations.
5. **TIER AWARENESS**: Prioritize CRITICAL and STANDARD modules for compliance fixes.
6. **NO PSEUDO-CONTRACTS (CRITICAL)**: You are STRICTLY FORBIDDEN from using automated scripts (e.g., Python/Bash/sed) to mechanically inject boilerplate, placeholders, or "pseudo-contracts" merely to artificially inflate the compliance score. Every semantic tag, anchor, and contract you add MUST reflect a genuine, deep understanding of the code's actual logic and business requirements.
7. **ID NAMING (CRITICAL)**: NEVER use fully-qualified Python import paths in `[DEF:id:Type]`. Use short, domain-driven semantic IDs (e.g., `[DEF:AuthService:Class]`). Follow the exact style shown in `.ai/standards/semantics.md`.
8. **ORPHAN PREVENTION**: To reduce the orphan count, you MUST physically wrap actual class and function definitions with `[DEF:id:Type] ... [/DEF]` blocks in the code. Modifying `@RELATION` tags does NOT fix orphans. The AST parser flags any unwrapped function as an orphan.
   - **Exception for Tests**: In test modules, use `BINDS_TO` to link major helpers to the module root. Small helpers remain C1 and don't need relations.
9. **DECISION-MEMORY CONTINUITY**: Audit ADR nodes, preventive task guardrails, and reactive Micro-ADR tags as one anti-regression chain. Missing or contradictory `@RATIONALE` / `@REJECTED` is a first-class semantic defect.

## Execution Steps

### 1. Reindex Semantic Workspace

Use MCP to refresh the semantic graph for the current workspace with [`reindex_workspace_tool`](.kilo/mcp.json).

### 2. Analyze Semantic Health

Use [`workspace_semantic_health_tool`](.kilo/mcp.json) and capture:
- `contracts`
- `relations`
- `orphans`
- `unresolved_relations`
- `files`

Treat high orphan counts and unresolved relations as first-class health indicators, not just informational noise.

### 3. Audit Critical Issues

Use [`audit_contracts_tool`](.kilo/mcp.json) and classify findings into:
- **Critical Parsing/Structure Errors**: malformed or incoherent semantic contract regions
- **Critical Contract Gaps**: missing [`@DATA_CONTRACT`](.ai/standards/semantics.md), [`@PRE`](.ai/standards/semantics.md), [`@POST`](.ai/standards/semantics.md), [`@SIDE_EFFECT`](.ai/standards/semantics.md) on CRITICAL contracts
- **Decision-Memory Gaps**:
  - missing standalone `[DEF:id:ADR]` for repo-shaping decisions
  - missing `@RATIONALE` / `@REJECTED` where task or implementation context clearly requires guardrails
  - retained workaround code without local reactive Micro-ADR tags
  - implementation that silently re-enables a path declared in upstream `@REJECTED`
- **Coverage Gaps**: missing [`@TIER`](.ai/standards/semantics.md), missing [`@PURPOSE`](.ai/standards/semantics.md)
- **Graph Breakages**: unresolved relations, broken references, isolated critical contracts, ADR nodes without downstream guarded contracts

### 4. Build Remediation Context

For the top failing contracts, use MCP semantic context tools such as [`get_semantic_context_tool`](.kilo/mcp.json), [`build_task_context_tool`](.kilo/mcp.json), [`impact_analysis_tool`](.kilo/mcp.json), and [`trace_tests_for_contract_tool`](.kilo/mcp.json) to understand:
1. Local contract intent
2. Upstream/downstream semantic impact
3. Related tests and fixtures
4. Whether relation recovery is needed
5. Whether decision-memory continuity is broken between ADR, task contract, and implementation

### 5. Execute Fixes (Optional/Handoff)

If $ARGUMENTS contains `fix` or `apply`:
- Handoff to the [`semantic`](.kilocodemodes) mode or a dedicated implementation agent instead of applying naive textual edits in orchestration.
- Require the fixing agent to prefer MCP contract mutation tools such as [`simulate_patch_tool`](.kilo/mcp.json), [`guarded_patch_contract_tool`](.kilo/mcp.json), [`patch_contract_tool`](.kilo/mcp.json), and [`infer_missing_relations_tool`](.kilo/mcp.json).
- Require the fixing agent to preserve or restore `@RATIONALE` / `@REJECTED` continuity whenever blocked-path knowledge exists.
- After changes, re-run reindex, health, and audit MCP steps to verify the delta.

### 6. Review Gate

Before completion, request or perform an MCP-based review path aligned with the [`reviewer-agent-auditor`](.kilocodemodes) mode so the workflow produces a semantic PASS/FAIL gate, not just a remediation list.

## Output

Provide a summary of the semantic state:
- **Health Metrics**: contracts / relations / orphans / unresolved_relations / files
- **Status**: [PASS/FAIL] (FAIL if CRITICAL gaps, rejected-path regressions, or semantically significant unresolved relations exist)
- **Top Issues**: List top 3-5 contracts or files needing attention.
- **Decision Memory**: summarize missing ADRs, missing guardrails, and rejected-path regression risks.
- **Action Taken**: Summary of MCP analysis performed, context gathered, and fixes or handoffs initiated.

## Context

$ARGUMENTS