ss-tools/.kilocode/workflows/speckit.semantics.md

description

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

User Input

$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, 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.

Execution Steps

1. Reindex Semantic Workspace

Use MCP to refresh the semantic graph for the current workspace with reindex_workspace_tool.

2. Analyze Semantic Health

Use workspace_semantic_health_tool 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 and classify findings into:

• Critical Parsing/Structure Errors: malformed or incoherent semantic contract regions
• Critical Contract Gaps: missing @DATA_CONTRACT, @PRE, @POST, @SIDE_EFFECT on CRITICAL contracts
• Coverage Gaps: missing @TIER, missing @PURPOSE
• Graph Breakages: unresolved relations, broken references, isolated critical contracts

4. Build Remediation Context

For the top failing contracts, use MCP semantic context tools such as get_semantic_context_tool, build_task_context_tool, impact_analysis_tool, and trace_tests_for_contract_tool to understand:

1. Local contract intent
2. Upstream/downstream semantic impact
3. Related tests and fixtures
4. Whether relation recovery is needed

5. Execute Fixes (Optional/Handoff)

If $ARGUMENTS contains fix or apply:

• Handoff to the semantic 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, guarded_patch_contract_tool, patch_contract_tool, and infer_missing_relations_tool.
• 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 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 or semantically significant unresolved relations exist)
• Top Issues: List top 3-5 contracts or files needing attention.
• Action Taken: Summary of MCP analysis performed, context gathered, and fixes or handoffs initiated.

Context

$ARGUMENTS