93 lines
5.8 KiB
Markdown
93 lines
5.8 KiB
Markdown
---
|
|
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
|