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.

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