busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

speckit.semantics update

Browse Source
This commit is contained in:
busya
2026-03-15 20:41:10 +03:00
parent 9ddb6a7911
commit 15d3141aef
3 changed files with 58 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.kilocode/mcp.json
View File

@@ -1 +1 @@
{"mcpServers":{"axiom-core":{"command":"/home/busya/dev/ast-mcp-core-server/.venv/bin/python","args":["-c","from src.server import main; main()"],"env":{"PYTHONPATH":"/home/busya/dev/ast-mcp-core-server"},"alwaysAllow":["reindex_workspace_tool","search_contracts_tool","read_grace_outline_tool","ast_search_tool","get_semantic_context_tool","build_task_context_tool","workspace_semantic_health_tool","audit_contracts_tool","diff_contract_semantics_tool","impact_analysis_tool","simulate_patch_tool","patch_contract_tool","guarded_patch_contract_tool","rename_contract_id_tool","move_contract_tool","extract_contract_tool","infer_missing_relations_tool","map_runtime_trace_to_contracts_tool","trace_tests_for_contract_tool","scaffold_contract_tests_tool"]}}}
{"mcpServers":{"axiom-core":{"command":"/home/busya/dev/ast-mcp-core-server/.venv/bin/python","args":["-c","from src.server import main; main()"],"env":{"PYTHONPATH":"/home/busya/dev/ast-mcp-core-server"},"alwaysAllow":["reindex_workspace_tool","read_grace_outline_tool","ast_search_tool","get_semantic_context_tool","build_task_context_tool","workspace_semantic_health_tool","audit_contracts_tool","diff_contract_semantics_tool","impact_analysis_tool","simulate_patch_tool","patch_contract_tool","guarded_patch_contract_tool","rename_contract_id_tool","move_contract_tool","extract_contract_tool","infer_missing_relations_tool","map_runtime_trace_to_contracts_tool","trace_tests_for_contract_tool","scaffold_contract_tests_tool"]}}}

72
.kilocode/workflows/speckit.semantics.md
View File

@@ -12,62 +12,68 @@ 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`. This involves generating the semantic map, analyzing compliance reports, and identifying critical parsing errors or missing metadata.
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. **STRICT ADHERENCE**: Follow `.ai/standards/semantics.md` for all anchor and tag syntax.
3. **NON-DESTRUCTIVE**: Do not remove existing code logic; only add or update semantic annotations.
4. **TIER AWARENESS**: Prioritize CRITICAL and STANDARD modules for compliance fixes.
5. **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" (such as `# @PURPOSE: Semantic contract placeholder.` or `# @PRE: Inputs satisfy function contract.`) merely to artificially inflate the compliance score. Every semantic tag, anchor, and contract you add MUST reflect a genuine, deep understanding of the specific code's actual logic and business requirements. Automated "stubbing" of semantics is classified as codebase corruption.
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. Generate Semantic Map
### 1. Reindex Semantic Workspace
Run the generator script from the repository root with the agent report option:
Use MCP to refresh the semantic graph for the current workspace with [`reindex_workspace_tool`](.kilocode/mcp.json).
```bash
python3 generate_semantic_map.py --agent-report
```
### 2. Analyze Semantic Health
### 2. Analyze Compliance Status
Use [`workspace_semantic_health_tool`](.kilocode/mcp.json) and capture:
- `contracts`
- `relations`
- `orphans`
- `unresolved_relations`
- `files`
**Parse the JSON output to identify**:
- `global_score`: The overall compliance percentage.
- `critical_parsing_errors_count`: Number of Priority 1 blockers.
- `priority_2_tier1_critical_missing_mandatory_tags_files`: Number of CRITICAL files needing metadata.
- `targets`: Status of key architectural files.
Treat high orphan counts and unresolved relations as first-class health indicators, not just informational noise.
### 3. Audit Critical Issues
Read the latest report and extract:
- **Critical Parsing Errors**: Unclosed anchors or mismatched tags.
- **Low-Score Files**: Files with score < 0.7 or marked with 🔴.
- **Missing Mandatory Tags**: Specifically for CRITICAL tier modules.
Use [`audit_contracts_tool`](.kilocode/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
- **Coverage Gaps**: missing [`@TIER`](.ai/standards/semantics.md), missing [`@PURPOSE`](.ai/standards/semantics.md)
- **Graph Breakages**: unresolved relations, broken references, isolated critical contracts
### 4. Formulate Remediation Plan
### 4. Build Remediation Context
Create a list of files requiring immediate attention:
1. **Priority 1**: Fix all "Critical Parsing Errors" (unclosed anchors).
2. **Priority 2**: Add missing mandatory tags for CRITICAL modules.
3. **Priority 3**: Improve coverage for STANDARD modules.
For the top failing contracts, use MCP semantic context tools such as [`get_semantic_context_tool`](.kilocode/mcp.json), [`build_task_context_tool`](.kilocode/mcp.json), [`impact_analysis_tool`](.kilocode/mcp.json), and [`trace_tests_for_contract_tool`](.kilocode/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. Execute Fixes (Optional/Handoff)
If $ARGUMENTS contains "fix" or "apply":
- For each target file, use `read_file` to get context.
- Apply semantic fixes using `apply_diff`, preserving all code logic.
- Re-run `python3 generate_semantic_map.py --agent-report` to verify the fix.
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`](.kilocode/mcp.json), [`guarded_patch_contract_tool`](.kilocode/mcp.json), [`patch_contract_tool`](.kilocode/mcp.json), and [`infer_missing_relations_tool`](.kilocode/mcp.json).
- 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:
- **Global Score**: [X]%
- **Status**: [PASS/FAIL] (FAIL if any Critical Parsing Errors exist)
- **Top Issues**: List top 3-5 files needing attention.
- **Action Taken**: Summary of maps generated or fixes applied.
- **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