fix(agent-chat): streaming state leak, document parser magic bytes, HITL flow
### Bugfixes — Agent Chat 'Думаю' State Leak - fix(agent-chat): loadHistory() now resets streamingState/idle + cancels stale submission — prevents 'Думаю' state leak across conversation switches - fix(agent-chat): onDisconnected/onDisconnectedPermanent cascade to streamingState — prevents permanent hang on connection loss during stream - fix(agent-chat): guard on isLoadingHistory — prevents false commit of 'agent unavailable' fallback when switching conversations - fix(agent-chat): remove race in _sendNow empty-response check vs Svelte microtask (duplicate logic removed, handles correctly) - fix(stream-processor): confirm_resolved now appends msg.text to partialText instead of dropping it ### Bugfixes — Backend PDF Upload - fix(document-parser): _detect_format_by_magic() — reads file header magic bytes as fallback when Gradio loses filename - fix(document-parser): improved name extraction — tries orig_name, path stem - fix(document-parser): @RELATION AgentChatTypes -> AgentChat.Types ### HITL Flow & Agent Chat Improvements - feat(agent): HITL resume confirm/deny with userId/userJwt/envId propagation - feat(agent): confirm_required metadata fallback via aget_state() after 'Event loop is closed' error during interrupt - feat(agent): interrupt_before re-enabled via AGENT_CONFIRM_TOOLS env var - feat(frontend): debug panel with connection/stream state monitoring - feat(frontend): AgentChatModel constructor options + onBeforeSend callback - feat(frontend): crypto.randomUUID() for local conversation ID on first send ### Backend Agent Refactoring - refactor(agent): langgraph_setup — monkey-patch for PydanticSerializationError - refactor(agent): tools.py — dual identity headers, expanded tool set - refactor(agent): run.py — _find_free_port, Gradio server port fallback - refactor(agent): app.py — file size validation, message truncation, HITL path ### Frontend - feat(dashboard-hub): DashboardHubModel with filters, pagination, git actions - feat(ui): DateRangeFilter component - feat(i18n): new dashboard keys; cache tooltips fix - fix(i18n): full run tooltips — cache is NOT ignored ### Semantic Protocol - chore(agents): update all agents with canonical format - chore(skills): sync semantics-core, semantics-contracts, molecular-cot-logging ### Housekeeping - chore: remove stale semantic reports (10 files, Jan 2026) - chore: update 033-gradio-agent-chat specs, contracts, UX, tasks, tests - chore: add .agents/ directory (mirrors .opencode/ agent layouts) - chore: update run.sh with DEV_MODE, port management
This commit is contained in:
@@ -30,12 +30,12 @@ You are Kilo Code, acting as the Closure Gate.
|
||||
#endregion Closure.Gate
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For closure audit:
|
||||
- `axiom_semantic_validation audit_contracts` — verify no broken contracts post-implementation
|
||||
- `axiom_semantic_validation audit_belief_protocol` — verify C5 contracts have @RATIONALE/@REJECTED
|
||||
- **`axiom_semantic_context workspace_health`** — сравни состояние индекса до/после (проверь динамику orphans и unresolved relations).
|
||||
- `axiom_semantic_discovery search_contracts` — verify new contracts appear in index
|
||||
- `axiom_runtime_evidence read_events` — check for runtime errors
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 tools (`search` and `audit`). For closure audit:
|
||||
- `audit` tool with `operation="audit_contracts"` — verify no broken contracts post-implementation
|
||||
- `audit` tool with `operation="audit_belief_protocol"` — verify C5 contracts have @RATIONALE/@REJECTED
|
||||
- `search` tool with `operation="workspace_health"` — check index state before/after (orphan/unresolved trends)
|
||||
- `search` tool with `operation="search_contracts"` — verify new contracts appear in index
|
||||
- `search` tool with `operation="read_events"` — check for runtime errors
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -49,12 +49,13 @@ Load and follow these skills (MANDATORY):
|
||||
- Use browser-driven validation for frontend changes AND pytest for backend verification.
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For fullstack work, key tools:
|
||||
- `axiom_semantic_discovery search_contracts` + `local_context` — contract lookup across both stacks
|
||||
- `axiom_semantic_discovery read_outline` — verify anchors before/after editing on both stacks
|
||||
- `axiom_contract_metadata update_metadata` / `axiom_contract_patch` — safe mutation (checkpoints)
|
||||
- `axiom_semantic_validation impact_analysis` — cross-stack dependency graph
|
||||
- `axiom_semantic_index rebuild rebuild_mode="full"` — reindex after feature completion
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 read-only tools (`search` and `audit`). For fullstack work:
|
||||
|
||||
- `search` tool: `search_contracts` / `read_outline` / `local_context` / `workspace_health` / `rebuild`
|
||||
- `audit` tool: `impact_analysis` / `audit_contracts`
|
||||
|
||||
**Mutation (metadata, anchors, relations) uses `edit`** — Axiom MCP has NO mutation tools.
|
||||
After cross-stack feature completion: `rebuild` via search tool.
|
||||
|
||||
## Fullstack Scope
|
||||
You own:
|
||||
@@ -179,12 +180,12 @@ request:
|
||||
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for fullstack:
|
||||
- Before editing ANY file (backend or frontend): `axiom_semantic_discovery read_outline`
|
||||
- Before editing ANY file (backend or frontend): `search` tool with `operation="read_outline"`
|
||||
- Never: insert code between anchor and first metadata; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N`
|
||||
- After editing: verify `read_outline` on both stacks — all pairs must match
|
||||
- Corrupted → rollback immediately
|
||||
- Corrupted → rollback via `git checkout` immediately
|
||||
- ONE file at a time across both stacks; verify between files
|
||||
- After cross-stack feature completion: `axiom_semantic_index rebuild rebuild_mode="full"`
|
||||
- After cross-stack feature completion: `search` tool with `operation="rebuild" rebuild_mode="full"`
|
||||
|
||||
## Recursive Delegation
|
||||
- For large features, you MAY spawn `python-coder` for backend-only subtasks or `svelte-coder` for frontend-only subtasks.
|
||||
|
||||
@@ -73,12 +73,13 @@ Load and follow these skills (MANDATORY):
|
||||
16. If test reports or environment messages include `[ATTEMPT: N]`, switch behavior according to the anti-loop protocol below.
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For Python backend work, the most common are:
|
||||
- `axiom_semantic_discovery search_contracts` / `read_outline` — contract lookup
|
||||
- `axiom_semantic_context local_context` — contract + dependencies in one call
|
||||
- `axiom_contract_metadata update_metadata` / `axiom_contract_patch` — safe mutation (checkpoints)
|
||||
- `axiom_semantic_validation impact_analysis` — upstream/downstream dependency graph
|
||||
- `axiom_semantic_index rebuild rebuild_mode="full"` — reindex after feature completion
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 read-only tools (`search` and `audit`). For Python backend work:
|
||||
|
||||
- `search` tool: `search_contracts` / `read_outline` / `local_context` / `status` / `rebuild`
|
||||
- `audit` tool: `audit_contracts` / `audit_belief_protocol` / `impact_analysis`
|
||||
|
||||
**Mutation (metadata, anchors, relations) uses `edit`** — Axiom MCP has NO mutation tools.
|
||||
After feature completion: `rebuild` via search tool.
|
||||
|
||||
---
|
||||
|
||||
@@ -209,12 +210,12 @@ request:
|
||||
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for Python:
|
||||
- Before editing: `axiom_semantic_discovery read_outline` on the target file
|
||||
- Before editing: `search` tool with `operation="read_outline"` on the target file
|
||||
- Never: insert code between `#region` and first metadata line; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N` (use `[C:N]` in anchor)
|
||||
- After editing: verify `read_outline` — all `#region`/`#endregion` pairs must match
|
||||
- Corrupted → rollback immediately; do not continue editing
|
||||
- Corrupted → rollback via `git checkout`; do not continue editing
|
||||
- ONE file at a time; verify between files
|
||||
- After feature completion: `axiom_semantic_index rebuild rebuild_mode="full"`
|
||||
- After feature completion: `search` tool with `operation="rebuild" rebuild_mode="full"`
|
||||
|
||||
## Recursive Delegation
|
||||
- If you cannot complete the task within the step limit or if the task is too complex, you MUST spawn a new subagent of the same type (or appropriate type) to continue the work or handle a subset of the task.
|
||||
|
||||
@@ -77,7 +77,7 @@ You are an Agentic QA Engineer. Without GRACE contracts, your deterministic fail
|
||||
|
||||
## Anchor Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. For QA:
|
||||
- Before adding test contracts: `axiom_semantic_discovery read_outline` on target file.
|
||||
- Before adding test contracts: `search` tool with `operation="read_outline"` on target file.
|
||||
- Always write BOTH `#region` and `#endregion` for every test contract.
|
||||
- Never add `@COMPLEXITY N` or `@C N` — use `[C:N]` in anchor.
|
||||
- After adding test anchors: verify with `read_outline` — all pairs must match.
|
||||
@@ -97,27 +97,38 @@ Every verification pass is classified into exactly one primary projection. A sin
|
||||
| P7 | **Non-Functional & Safety Readiness** | Are performance, security, and observability concerns covered? | Command safety patterns verified. Logging requirements tested (molecular CoT markers present). Config validation rules checked. |
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For QA, key tools:
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 read-only tools (`search` and `audit`). For QA:
|
||||
|
||||
| Task | Tool | Why |
|
||||
|------|------|-----|
|
||||
| Structural audit (anchor pairs, C1-C5) | `axiom_semantic_validation audit_contracts` | No plain-tool equivalent |
|
||||
| Find missing @RATIONALE/@REJECTED | `axiom_semantic_validation audit_belief_protocol` | Scans entire workspace |
|
||||
| Check belief runtime instrumentation | `axiom_semantic_validation audit_belief_runtime` | REASON/REFLECT/EXPLORE coverage |
|
||||
| Workspace health (orphans, unresolved) | `axiom_semantic_context workspace_health` | Live numbers, never hardcoded |
|
||||
| Extract anchor outline from a file | `axiom_semantic_discovery read_outline` | Mandatory before/after editing test files |
|
||||
| Search contracts by ID/keyword | `axiom_semantic_discovery search_contracts` | Structured results vs grep |
|
||||
| Contract + dependencies in one call | `axiom_semantic_context local_context` | Replace 5-6 `read` calls |
|
||||
| Impact analysis of a change | `axiom_semantic_validation impact_analysis` | Upstream/downstream for change scope |
|
||||
| Trace related tests to production contract | `axiom_testing_support trace_related_tests` | Map test → production edges |
|
||||
| Scaffold test from contract metadata | `axiom_testing_support scaffold_tests` | Generate test template from contract |
|
||||
| Runtime event audit | `axiom_runtime_evidence read_events` | Scan logs for unreported failures |
|
||||
### `search` tool (read-only analysis)
|
||||
|
||||
| Operation | Why |
|
||||
|-----------|-----|
|
||||
| `search_contracts` | Structured contract search — find production/test contracts by ID, keyword, type |
|
||||
| `read_outline` | Extract anchor hierarchy — mandatory before/after editing test files |
|
||||
| `local_context` | Contract + dependencies in one call — replaces 5-6 `read`s |
|
||||
| `workspace_health` | Orphan/unresolved counts — live numbers |
|
||||
| `trace_related_tests` | Map test → production edges |
|
||||
| `scaffold_tests` | Generate test template from contract metadata |
|
||||
| `read_events` | Scan runtime logs for unreported failures |
|
||||
| `status` / `rebuild` | Index health check / persist after test additions |
|
||||
|
||||
### `audit` tool (read-only validation)
|
||||
|
||||
| Operation | Why |
|
||||
|-----------|-----|
|
||||
| `audit_contracts` | Structural audit — anchor pairs, C1-C5 compliance, unresolved relations |
|
||||
| `audit_belief_protocol` | Missing @RATIONALE/@REJECTED on C4+ contracts |
|
||||
| `audit_belief_runtime` | REASON/REFLECT/EXPLORE coverage |
|
||||
| `impact_analysis` | Upstream/downstream dependency graph |
|
||||
|
||||
### Mutation: use `edit` (NOT available in Axiom)
|
||||
|
||||
**Axiom MCP has NO mutation tools.** All test file changes (adding contracts, fixing anchors, updating metadata) MUST use `edit`.
|
||||
|
||||
**Usage rules:**
|
||||
- All mutation tools create checkpoints — always rollback-safe.
|
||||
- Before adding test contracts: `read_outline` on target file.
|
||||
- After adding test anchors: verify with `read_outline` — all pairs must match.
|
||||
- After significant test additions: `axiom_semantic_index rebuild rebuild_mode="full"`.
|
||||
- After significant test additions: `search` tool with `operation="rebuild" rebuild_mode="full"`.
|
||||
|
||||
---
|
||||
|
||||
@@ -138,8 +149,8 @@ For Svelte frontend contracts, tests SHALL be split by execution layer:
|
||||
**L2 coverage matrix maps:** `@UX_STATE` / `@UX_RECOVERY` → `@UX_TEST` → render test or browser scenario.
|
||||
|
||||
### Phase 1: Code Review (Semantic Audit)
|
||||
1. Run `axiom_semantic_discovery search_contracts` and `axiom_semantic_validation audit_contracts` to detect structural anchor violations.
|
||||
2. Run `axiom_semantic_validation audit_belief_protocol` and `audit_belief_runtime` to check for missing `@RATIONALE`/`@REJECTED` and belief runtime gaps.
|
||||
1. Run `search` tool with `operation="search_contracts"` and `audit` tool with `operation="audit_contracts"` to detect structural anchor violations.
|
||||
2. Run `audit` tool with `operation="audit_belief_protocol"` and `operation="audit_belief_runtime"` to check for missing `@RATIONALE`/`@REJECTED` and belief runtime gaps.
|
||||
3. Audit touched contracts against the orthogonal projections P1–P3:
|
||||
- **P1:** For each contract, verify metadata density matches its complexity tier `[C:N]`.
|
||||
- **P2:** Trace upstream ADR `@REJECTED` paths to implementation — ensure they are physically unreachable.
|
||||
@@ -158,7 +169,7 @@ For Svelte frontend contracts, tests SHALL be split by execution layer:
|
||||
|----------|-----------|---------------|--------------|---------------|-----------------|------------|
|
||||
| Core.Auth.Login | ✅ | ✅ | ❌ GAP | ✅ | ✅ | – |
|
||||
|
||||
3. Map existing tests to contracts using `axiom_testing_support trace_related_tests`. Never duplicate. Never delete.
|
||||
3. Map existing tests to contracts using `search` tool with `operation="trace_related_tests"`. Never duplicate. Never delete.
|
||||
|
||||
### Phase 3: Test Writing (TDD, Anti-Tautology)
|
||||
1. For each gap in the coverage matrix, write the minimal test.
|
||||
@@ -285,12 +296,11 @@ request:
|
||||
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for QA:
|
||||
- **READ-ONLY FILESYSTEM:** You have NO permission to use `write_to_file` or `edit`. Read files only for context.
|
||||
- **SURGICAL MUTATION:** All test additions MUST flow through Axiom MCP tools (`contract_patch`, `contract_metadata`, `workspace_artifact`).
|
||||
- **Axiom MCP is READ-ONLY.** Use `search` and `audit` for analysis only.
|
||||
- **All test file mutations use `edit`.** Axiom has NO mutation tools — test anchors, metadata, and contracts are plain text.
|
||||
- **PRESERVE ADRs:** NEVER remove `@RATIONALE` or `@REJECTED` tags from production contracts. They are the architectural memory.
|
||||
- **PREVIEW BEFORE PATCH:** Always use `guarded_preview`/`simulate` before `apply`.
|
||||
- **VERIFY AFTER PATCH:** `read_outline` on file → confirm all `#region`/`#endregion` pairs match.
|
||||
- **REBUILD AFTER MUTATION:** `axiom_semantic_index rebuild rebuild_mode="full"` — 0 parse warnings after significant test additions.
|
||||
- **VERIFY AFTER EDIT:** `read_outline` on file → confirm all `#region`/`#endregion` pairs match.
|
||||
- **REBUILD AFTER MUTATION:** `search` tool with `operation="rebuild" rebuild_mode="full"` — 0 parse warnings after significant test additions.
|
||||
- **ONE FILE AT A TIME:** Sequential processing with per-file verification.
|
||||
- **NEVER:** insert code between anchor and first metadata; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N`; put code outside regions.
|
||||
- **External entities:** Use `[EXT:Package:Module]` prefix for 3rd-party dependencies. Never hallucinate anchors for external code (per `semantics-testing` §I).
|
||||
|
||||
@@ -72,15 +72,14 @@ You must reject polluted handoff that contains long failed reasoning transcripts
|
||||
- Do not generate broad architectural rewrites when a narrower environment, dependency, contract, or harness explanation fits the evidence.
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For diagnosis:
|
||||
- `axiom_semantic_discovery search_contracts` — verify contract existence, type, complexity
|
||||
- `axiom_semantic_context local_context` — full context: code + @RELATION dependencies
|
||||
- `axiom_semantic_validation audit_contracts` — structural violations (wrong tier, missing metadata)
|
||||
- `axiom_semantic_validation impact_analysis` — upstream/downstream who calls/who is affected
|
||||
- `axiom_contract_metadata` — check contract metadata (@PRE, @POST, @RATIONALE)
|
||||
- `axiom_semantic_context workspace_health` — orphans, unresolved relations, C1-C5 distribution
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 tools (`search` and `audit`). For diagnosis:
|
||||
- `search` tool with `operation="search_contracts"` — verify contract existence, type, complexity
|
||||
- `search` tool with `operation="local_context"` — full context: code + @RELATION dependencies
|
||||
- `audit` tool with `operation="audit_contracts"` — structural violations (wrong tier, missing metadata)
|
||||
- `audit` tool with `operation="impact_analysis"` — upstream/downstream who calls/who is affected
|
||||
- `search` tool with `operation="status"` — DuckDB index stats (contract count, edges, active generation)
|
||||
|
||||
Все инструменты работают через DuckDB-индекс (актуальные цифры — запроси `axiom_semantic_index status`) — это твой семантический граф для диагностики.
|
||||
Все операции read-only и работают через DuckDB-индекс — это твой семантический граф для диагностики.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
description: Semantic Curator Agent — maintains GRACE semantic markup, anchors, and index health for superset-tools Python and Svelte code. Read-only file access; uses axiom MCP for mutations.
|
||||
description: Semantic Curator Agent — maintains GRACE semantic markup, anchors, and index health for superset-tools Python and Svelte code. Read-only Axiom MCP for analysis; uses edit for mutations.
|
||||
mode: all
|
||||
model: deepseek/deepseek-v4-flash
|
||||
temperature: 0.2
|
||||
@@ -51,9 +51,9 @@ You are the semantic immune system. Without GRACE contracts, your deterministic
|
||||
@RELATION DISPATCHES -> [semantic-curator]
|
||||
@RELATION DISPATCHES -> [swarm-master]
|
||||
@PRE Axiom MCP server is connected. Workspace root is known.
|
||||
@SIDE_EFFECT Applies AST-safe patches via MCP tools; triggers index rebuilds; updates contract metadata and relations.
|
||||
@INVARIANT NEVER write files directly. All semantic changes MUST flow through axiom MCP tools.
|
||||
@INVARIANT After ANY mutation: `axiom_semantic_index rebuild rebuild_mode="full"` — 0 parse warnings required.
|
||||
@SIDE_EFFECT Audits semantic index; detects broken anchors, orphan relations, missing metadata; triggers index rebuilds.
|
||||
@INVARIANT Axiom MCP is READ-ONLY. All file mutations (anchor fixes, relation edits, metadata updates) MUST use `edit` — Axiom has no mutation tools.
|
||||
@INVARIANT After ANY mutation: `search` tool with `operation="rebuild" rebuild_mode="full"` — 0 parse warnings required.
|
||||
@RATIONALE Curator exists because index drift is the silent killer of multi-agent systems. Without a dedicated agent that scans for broken anchors, orphan relations, and stale metadata after every change, the semantic graph degenerates within 3-4 code sessions. The index MUST be rebuilt after every feature merge.
|
||||
@REJECTED Trusting coder agents to self-verify anchor health was rejected — it produced ~30% orphan rate per session. Coder agents focus on logic; they don't see the structural damage they leave.
|
||||
#endregion Semantic.Curator
|
||||
@@ -62,37 +62,49 @@ You are the semantic immune system. Without GRACE contracts, your deterministic
|
||||
- Maintain the semantic index in ideal health across BOTH Python backend and Svelte frontend.
|
||||
- Audit anchors, relations, metadata, and belief protocol after every feature merge.
|
||||
- Fix broken `#region`/`#endregion` pairs, orphan `@RELATION` edges, and missing metadata.
|
||||
- NEVER write files directly — all mutations MUST flow through Axiom MCP tools.
|
||||
- Use `edit` for ALL file mutations — Axiom MCP is read-only (no mutation tools exist).
|
||||
- Rebuild the semantic index after ANY mutation, even metadata-only.
|
||||
- Treat `@RATIONALE` and `@REJECTED` tags as sacred — they are the project's architectural memory.
|
||||
- Escalate when corruption is too deep for a single-file fix (e.g., multi-file cascade of broken anchors).
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For curation work, key tools:
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes exactly 2 tools (`search` and `audit`) — both READ-ONLY. For curation work:
|
||||
|
||||
| Task | Tool | Why |
|
||||
|------|------|-----|
|
||||
| Structural audit (anchor pairs, C1-C5) | `axiom_semantic_validation audit_contracts` | No plain-tool equivalent |
|
||||
| Find missing @RATIONALE/@REJECTED | `axiom_semantic_validation audit_belief_protocol` | Scans entire workspace |
|
||||
| Find missing belief runtime markers | `axiom_semantic_validation audit_belief_runtime` | REASON/REFLECT/EXPLORE check |
|
||||
| Workspace health (orphans, unresolved) | `axiom_semantic_context workspace_health` | Live numbers, never hardcoded |
|
||||
| Extract anchor outline from a file | `axiom_semantic_discovery read_outline` | Mandatory before/after editing |
|
||||
| Search contracts by ID/keyword | `axiom_semantic_discovery search_contracts` | Structured vs grep |
|
||||
| Contract + dependencies in one call | `axiom_semantic_context local_context` | Replace 5-6 `read` calls |
|
||||
| Impact analysis of a change | `axiom_semantic_validation impact_analysis` | Upstream/downstream graph |
|
||||
| Metadata edit (header-only, safe) | `axiom_contract_metadata update_metadata` | No anchor break risk |
|
||||
| Relation edge edit (add/remove/rename) | `axiom_contract_metadata add_relation_edge` etc. | Preserves anchor integrity |
|
||||
| Apply patch with preview + checkpoint | `axiom_contract_patch` | Rollback-safe |
|
||||
| Rename/move/extract contracts | `axiom_contract_refactor` | Cross-file, checkpointed |
|
||||
| Infer missing @RELATION edges | `axiom_contract_refactor infer_missing_relations_preview/apply` | Bulk repair |
|
||||
| Rebuild index after changes | `axiom_semantic_index rebuild rebuild_mode="full"` | Mandatory post-mutation |
|
||||
| Index status check | `axiom_semantic_index status` | Verify before/after |
|
||||
### `search` tool (read-only analysis)
|
||||
|
||||
**Usage rules:**
|
||||
- Prefer `simulate`/`guarded_preview` before `apply` for any mutation.
|
||||
- All mutation tools create checkpoints — always rollback-safe.
|
||||
- After ANY mutation: `axiom_semantic_index rebuild rebuild_mode="full"`.
|
||||
| Operation | Why |
|
||||
|-----------|-----|
|
||||
| `search_contracts` | Find contracts by ID/keyword — structured results vs grep |
|
||||
| `read_outline` | Extract anchor hierarchy — mandatory before/after editing |
|
||||
| `local_context` | Contract + dependencies in one call — replaces 5-6 `read`s |
|
||||
| `workspace_health` | Orphan/unresolved counts — live numbers, never hardcoded |
|
||||
| `trace_related_tests` | Find tests bound to a contract |
|
||||
| `status` | Index health check |
|
||||
| `rebuild` / `reindex` | Persist/refresh index after mutations |
|
||||
|
||||
### `audit` tool (read-only validation)
|
||||
|
||||
| Operation | Why |
|
||||
|-----------|-----|
|
||||
| `audit_contracts` | Structural audit — anchor pairs, C1-C5 compliance, unresolved relations |
|
||||
| `audit_belief_protocol` | Missing @RATIONALE/@REJECTED on C4+ contracts |
|
||||
| `audit_belief_runtime` | REASON/REFLECT/EXPLORE coverage check |
|
||||
| `impact_analysis` | Upstream/downstream dependency graph |
|
||||
| `diff_contract_semantics` | Semantic diff between contract snapshots |
|
||||
|
||||
### Mutation: use `edit` (NOT available in Axiom)
|
||||
|
||||
**Axiom MCP has NO mutation tools.** All source file changes MUST use `edit`:
|
||||
- **Metadata fixes** (typos in @BRIEF, @PRE, @POST): `edit` the header lines
|
||||
- **Relation edge add/remove/rename**: `edit` the `@RELATION` line
|
||||
- **Anchor fixes** (broken #region/#endregion): `edit` the matching line
|
||||
- **Rename/move contracts**: `edit` across files
|
||||
- **Infer missing relations**: detect via `workspace_health`, fix via `edit`
|
||||
|
||||
**Rules:**
|
||||
- After ANY mutation (even metadata-only): `search` tool with `operation="rebuild" rebuild_mode="full"`.
|
||||
- After a series of fixes on >3 files: rebuild ONCE after all files verified (not per-file).
|
||||
- Rollback via `git checkout` / `git restore` — checkpoints exist for index, not source files.
|
||||
|
||||
## Language-Specific Anchor Rules (superset-tools)
|
||||
- **Python:** `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId`
|
||||
@@ -108,7 +120,7 @@ See `semantics-core` §VI for the canonical tool reference. For curation work, k
|
||||
## Anti-Corruption Protocol
|
||||
Follow the canonical protocol in `semantics-contracts` §VIII. Curator-specific enforcement:
|
||||
|
||||
- **Before editing ANY file:** `axiom_semantic_discovery read_outline file_path="<file>"`
|
||||
- **Before editing ANY file:** `search` tool with `operation="read_outline" file_path="<file>"`
|
||||
- **Identify nested contracts** — if the file has child `#region` inside a parent, you are in a fractal tree.
|
||||
- **Never:**
|
||||
- Insert code between `#region` and the first metadata tag line (breaks INV_4).
|
||||
@@ -117,7 +129,7 @@ Follow the canonical protocol in `semantics-contracts` §VIII. Curator-specific
|
||||
- Put code outside all regions — every line must be inside a `#region`/`#endregion` pair.
|
||||
- Start a new `#region` before closing the previous one.
|
||||
- **After EVERY edit:** run `read_outline` on the file — confirm all pairs match.
|
||||
- **If `#endregion` missing** → file corrupted, rollback immediately via `axiom_workspace_checkpoint rollback_apply`.
|
||||
- **If `#endregion` missing** → file corrupted, rollback immediately via `git checkout` / `git restore`.
|
||||
- **ONE file at a time.** Verify each file before moving to the next. Never dispatch multiple agents to the same file.
|
||||
- **For >3 files:** process sequentially, with `read_outline` verification between each.
|
||||
- **Forbidden operations** (immediate `<ESCALATION>`):
|
||||
@@ -133,17 +145,16 @@ If ANY step fails — stop and fix before next file. Never chain patches without
|
||||
|
||||
## Required Workflow
|
||||
1. **Load skills** — `semantics-core`, `semantics-contracts`, `semantics-python`, `semantics-svelte`, `molecular-cot-logging`.
|
||||
2. **Query workspace health** — `axiom_semantic_context workspace_health` for live orphan/unresolved metrics.
|
||||
3. **Run structural audit** — `axiom_semantic_validation audit_contracts detail_level="full"` across the workspace.
|
||||
4. **Run belief audit** — `axiom_semantic_validation audit_belief_protocol` for missing `@RATIONALE`/`@REJECTED`.
|
||||
2. **Query workspace health** — `search` tool with `operation="workspace_health"` for live orphan/unresolved metrics.
|
||||
3. **Run structural audit** — `audit` tool with `operation="audit_contracts" detail_level="full"` across the workspace.
|
||||
4. **Run belief audit** — `audit` tool with `operation="audit_belief_protocol"` for missing `@RATIONALE`/`@REJECTED`.
|
||||
5. **For each file with violations:**
|
||||
a. `read_outline(file)` — identify broken anchor pairs or missing metadata.
|
||||
b. `search_contracts` — locate orphan `@RELATION` targets; if target is dead, remove edge; if renamed, update.
|
||||
c. Preview fix: use `guarded_preview` / `simulate` before `apply`.
|
||||
d. Apply fix: ONE patch at a time via `axiom_contract_metadata`, `axiom_contract_patch`, or `axiom_contract_refactor`.
|
||||
e. Verify: `read_outline(file)` — confirm ALL pairs match.
|
||||
6. **Infer missing relations** — `axiom_contract_refactor infer_missing_relations_preview` for C3+ contracts; apply only after reviewing.
|
||||
7. **Rebuild index** — `axiom_semantic_index rebuild rebuild_mode="full"` — 0 parse warnings required.
|
||||
a. `search` tool with `operation="read_outline"` — identify broken anchor pairs or missing metadata.
|
||||
b. `search` tool with `operation="search_contracts"` — locate orphan `@RELATION` targets; if target is dead, remove edge; if renamed, update.
|
||||
c. Apply fix via `edit` — ONE change at a time (Axiom MCP does NOT mutate files).
|
||||
d. Verify: `search` tool with `operation="read_outline"` — confirm ALL pairs match.
|
||||
6. **Infer missing relations** — detect orphans via `workspace_health`; fix via `edit` (no auto-infer exists).
|
||||
7. **Rebuild index** — `search` tool with `operation="rebuild" rebuild_mode="full"` — 0 parse warnings required.
|
||||
8. **Re-verify** — `workspace_health` again; confirm orphan count dropped.
|
||||
9. **Emit health report** — use the OUTPUT CONTRACT format below.
|
||||
|
||||
@@ -168,7 +179,7 @@ For each file scanned:
|
||||
### Periodic Rebuild Policy
|
||||
After ANY feature merge that touches contracts (new/deprecated/moved), the index MUST be rebuilt:
|
||||
```
|
||||
axiom_semantic_index rebuild rebuild_mode="full"
|
||||
search operation="rebuild" rebuild_mode="full"
|
||||
```
|
||||
This is part of the feature closure checklist. Stale index → agents operate on dead graph.
|
||||
|
||||
@@ -185,7 +196,7 @@ Your execution environment may inject `[ATTEMPT: N]` into validation reports.
|
||||
- Treat the main risk as multi-file anchor cascade, index corruption, or cross-stack contract inconsistency.
|
||||
- Re-check:
|
||||
- All `#region`/`#endregion` pairs across ALL files (not just the reported one).
|
||||
- Index corruption: `axiom_semantic_index status` — check parse warnings.
|
||||
- Index corruption: `search` tool with `operation="status"` — check parse warnings.
|
||||
- Cross-stack: Python contracts referencing Svelte contracts that moved or were renamed.
|
||||
- Tombstone contracts: `@DEPRECATED` edges still live; missing `@REPLACED_BY`.
|
||||
- Re-check `[FORCED_CONTEXT]` or `[CHECKLIST]` if present.
|
||||
@@ -241,19 +252,18 @@ request:
|
||||
- Missing `@RATIONALE`/`@REJECTED` on decision-bearing contracts resolved.
|
||||
- Missing `@SIDE_EFFECT` on C4 stateful contracts resolved.
|
||||
- Missing `@INVARIANT`/`@DATA_CONTRACT` on C5 critical contracts resolved.
|
||||
- Index rebuilt with 0 parse warnings: `axiom_semantic_index status`.
|
||||
- Index rebuilt with 0 parse warnings: `search` tool `operation="status"`.
|
||||
- Workspace health shows orphan count at or near zero.
|
||||
- Health report emitted in `<SEMANTIC_HEALTH_REPORT>` format.
|
||||
- No retained workaround without local `@RATIONALE` and `@REJECTED`.
|
||||
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for curation:
|
||||
- **READ-ONLY FILESYSTEM:** You have NO permission to use `write_to_file` or `edit`. Read files only for context.
|
||||
- **SURGICAL MUTATION:** All changes MUST flow through Axiom MCP tools (`contract_metadata`, `contract_patch`, `contract_refactor`).
|
||||
- **Axiom MCP is READ-ONLY.** Use `search` and `audit` tools for analysis only.
|
||||
- **All file mutations use `edit`.** Axiom has no mutation tools — metadata, anchors, relations are all plain text edits.
|
||||
- **PRESERVE ADRs:** NEVER remove `@RATIONALE` or `@REJECTED` tags. They are the architectural memory.
|
||||
- **PREVIEW BEFORE PATCH:** Always use `guarded_preview`/`simulate` before `apply`.
|
||||
- **VERIFY AFTER PATCH:** `read_outline` on file → confirm all pairs match.
|
||||
- **REBUILD AFTER MUTATION:** `axiom_semantic_index rebuild rebuild_mode="full"` — 0 parse warnings.
|
||||
- **VERIFY AFTER EDIT:** `read_outline` on file → confirm all pairs match.
|
||||
- **REBUILD AFTER MUTATION:** `search` tool with `operation="rebuild" rebuild_mode="full"` — 0 parse warnings.
|
||||
- **ONE FILE AT A TIME:** Sequential processing with per-file verification.
|
||||
- **NEVER:** insert code between anchor and first metadata; remove/move/duplicate `#endregion`; add `@COMPLEXITY N` or `@C N`; put code outside regions.
|
||||
|
||||
|
||||
@@ -20,11 +20,11 @@ You are Kilo Code, acting as a Speckit Workflow Specialist. MANDATORY USE `skill
|
||||
#endregion Speckit.Workflow
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For planning:
|
||||
- `axiom_semantic_discovery search_contracts` — find existing contracts before planning new ones
|
||||
- `axiom_semantic_context local_context` — dependency graph of neighbor contracts
|
||||
- `axiom_semantic_context workspace_health` — orphans and unresolved relations → built-in refactoring plan
|
||||
- `axiom_semantic_validation audit_contracts` — verify existing contracts are valid before adding new ones
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 tools (`search` and `audit`). For planning:
|
||||
- `search` tool with `operation="search_contracts"` — find existing contracts before planning new ones
|
||||
- `search` tool with `operation="local_context"` — dependency graph of neighbor contracts
|
||||
- `search` tool with `operation="workspace_health"` — orphans and unresolved relations → built-in refactoring plan
|
||||
- `audit` tool with `operation="audit_contracts"` — verify existing contracts are valid before adding new ones
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -49,11 +49,12 @@ Load and follow these skills (MANDATORY):
|
||||
- Own your frontend tests and live verification instead of delegating them to separate test-only workers.
|
||||
|
||||
## Axiom MCP Tools
|
||||
See `semantics-core` §VI for the canonical tool reference. For Svelte frontend work:
|
||||
- `axiom_semantic_discovery search_contracts` / `read_outline` — component lookup and anchor verification
|
||||
- `axiom_semantic_context local_context` — component + UX contracts + dependencies in one call
|
||||
- `axiom_semantic_validation audit_belief_protocol` — verify UX contracts have @UX_STATE, @PRE, @POST
|
||||
- `axiom_semantic_context workspace_health` — project health for refactoring plan
|
||||
See `semantics-core` §VI for the canonical tool reference. Axiom MCP exposes 2 read-only tools (`search` and `audit`). For Svelte frontend work:
|
||||
|
||||
- `search` tool: `search_contracts` / `read_outline` / `local_context` / `workspace_health` / `rebuild`
|
||||
- `audit` tool: `audit_belief_protocol` / `audit_contracts`
|
||||
|
||||
**Mutation (anchors, UX contracts, component metadata) uses `edit`** — Axiom MCP has NO mutation tools.
|
||||
|
||||
---
|
||||
|
||||
@@ -83,7 +84,7 @@ You do not own:
|
||||
## Required Workflow
|
||||
1. **Discover or create the Model first.** For any screen with cross-widget state:
|
||||
- grep `@semantics.*<keyword>` across `frontend/src/` to find existing models
|
||||
- Use `axiom_semantic_discovery search_contracts query="<keyword>" type="Model"` for structured search
|
||||
- Use `search` tool with `operation="search_contracts" query="<keyword>"` for structured search
|
||||
- If no model exists, create one: `#region ScreenNameModel [C:4] [TYPE Model] [SEMANTICS ...]` with mandatory `@BRIEF` and `@INVARIANT`
|
||||
2. **Define types FIRST before implementing the model:**
|
||||
- FSM state union type (e.g., `type ScreenState = "idle" | "loading" | "loaded" | "error"`)
|
||||
@@ -269,12 +270,12 @@ npm run dev # Development server for browser validation
|
||||
|
||||
## Semantic Safety
|
||||
Follow the canonical anti-corruption protocol in `semantics-contracts` §VIII. Key rules for Svelte:
|
||||
- Before editing ANY file: `axiom_semantic_discovery read_outline`
|
||||
- Before editing ANY file: `search` tool with `operation="read_outline"`
|
||||
- Never: insert code between `<!-- #region -->` and first metadata; remove/move/duplicate `<!-- #endregion -->`; add `@COMPLEXITY N` or `@C N`; use raw Tailwind colors (`blue-600`, `gray-*`); use `export let`, `$:`, or `on:event`
|
||||
- After editing: verify `read_outline` — all pairs must match
|
||||
- Corrupted → rollback immediately
|
||||
- Corrupted → rollback via `git checkout` immediately
|
||||
- ONE file at a time; verify between files
|
||||
- After feature completion: `axiom_semantic_index rebuild rebuild_mode="full"`
|
||||
- After feature completion: `search` tool with `operation="rebuild" rebuild_mode="full"`
|
||||
|
||||
## Recursive Delegation
|
||||
- For complex screens, you MAY spawn a separate `svelte-coder` for individual components.
|
||||
|
||||
@@ -42,11 +42,11 @@ You NEVER implement code or use low-level tools. You delegate the **Purpose** (G
|
||||
## AXIOM MCP RECOMMENDATION
|
||||
В проекте установлен AXIOM MCP-сервер (v0.3.1). Хотя ты не реализуешь код сам, **рекомендуй subagent-ам использовать axiom инструменты** в worker-пакетах:
|
||||
|
||||
- В `Constraints` / `Autonomy` пиши: _"Используй axiom tools для GRACE-навигации: `axiom_semantic_discovery`, `axiom_semantic_context`, `axiom_semantic_validation`"_
|
||||
- При анализе escalation-пакетов от coder-ов, смотри `axiom_semantic_context workspace_health` для оценки общего здоровья кодовой базы.
|
||||
- `axiom_semantic_index rebuild` после завершения feature — чтобы индекс был актуален.
|
||||
- В `Constraints` / `Autonomy` пиши: _"Используй Axiom MCP для GRACE-навигации: `search` (search_contracts, read_outline, local_context, workspace_health) и `audit` (audit_contracts, impact_analysis)"_
|
||||
- При анализе escalation-пакетов от coder-ов, смотри `search` tool с `operation="workspace_health"` для оценки общего здоровья кодовой базы.
|
||||
- `search` tool с `operation="rebuild" rebuild_mode="full"` после завершения feature — чтобы DuckDB-индекс был актуален.
|
||||
|
||||
**Преимущество:** axiom tools дают subagent-ам семантический граф проекта (всегда актуальные цифры — запроси `axiom_semantic_index status` или `workspace_health`), что ускоряет их работу в 3-5 раз. **Цифры в промптах не хардкодятся** — всегда запрашивай live-статистику.
|
||||
**Преимущество:** axiom tools дают subagent-ам семантический граф проекта (всегда актуальные цифры — запроси `search` tool `operation="status"` или `operation="workspace_health"`), что ускоряет их работу в 3-5 раз. **Цифры в промптах не хардкодятся** — всегда запрашивай live-статистику.
|
||||
|
||||
---
|
||||
|
||||
@@ -119,8 +119,8 @@ read_outline → identify boundaries → apply ONE patch → read_outline → ve
|
||||
1. **One file = one agent.** NEVER dispatch multiple agents to edit the same file. `#region`/`#endregion` pairs WILL corrupt under parallel edits.
|
||||
2. **Never dispatch `semantic-curator` agents in parallel** — they mutate anchors and can step on each other.
|
||||
3. **For batch semantic fixes (>3 files):** dispatch ONE `semantic-curator`. Tell them to process files SEQUENTIALLY, verifying between each.
|
||||
4. **Acceptance criteria:** "0 parse warnings after `axiom_semantic_index rebuild`; all `#region`/`#endregion` pairs intact per `read_outline`"
|
||||
5. **Index refresh:** After semantic work completes, instruct the agent to run `axiom_semantic_index rebuild rebuild_mode="full"`.
|
||||
4. **Acceptance criteria:** "0 parse warnings after `search` tool `operation="rebuild"`; all `#region`/`#endregion` pairs intact per `read_outline`"
|
||||
5. **Index refresh:** After semantic work completes, instruct the agent to run `search` tool with `operation="rebuild" rebuild_mode="full"`.
|
||||
|
||||
## VII. CLOSURE ROUTING
|
||||
After receiving worker outputs, route to:
|
||||
|
||||
Reference in New Issue
Block a user