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

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
• 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, missing @PURPOSE
• 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, 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. 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 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.
• 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 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