114 lines
8.5 KiB
Markdown
114 lines
8.5 KiB
Markdown
---
|
|
name: semantic-curation
|
|
description: Operating protocol for the semantic curator — maintain GRACE-Poly anchors, relations, metadata, and index health. Load when repairing semantic markup, fixing orphan relations, de-duplicating metadata, or rebuilding the index after implementation.
|
|
---
|
|
|
|
#region Self.Curation [C:5] [TYPE Skill] [SEMANTICS curation,anchors,relations,index,health]
|
|
@BRIEF HOW the semantic curator keeps the GRACE-Poly graph alive: audit, repair one file at a time, verify, rebuild, and report — as a leaf worker in the self-orchestration flow.
|
|
@RELATION DEPENDS_ON -> [Std.Semantics.Core]
|
|
@RELATION DEPENDS_ON -> [Std.Semantics.Contracts]
|
|
@RELATION CALLED_BY -> [Self.Orchestrator]
|
|
@RATIONALE The semantic graph is the shared nervous system of every agent in the flow. When an implementer edits code it can silently break a #region/#endregion pair, orphan a @RELATION edge, or leave a decision undocumented — and a broken anchor makes every downstream contract invisible to the attention pipeline, so the next agent confabulates instead of navigating. A dedicated curator is the only thing standing between "one bad edit" and "every agent operating on half the codebase". The curator never writes logic; it repairs STRUCTURE (anchors, relations, metadata, index), which is why it can touch many files — but only one at a time, with verification between each.
|
|
@REJECTED Trusting implementers to self-verify anchor health — the graph degenerates within a few sessions without a curator. Filling missing @-tags from audit checklists was rejected — synthetic markup is worse than a bare anchor (INV_9). Fixing structure inside the implementer's own context was rejected — that context is saturated with feature logic. Parallel curation was rejected — two curators on one file corrupt `#endregion` pairs.
|
|
@INVARIANT Axiom MCP is read-only for analysis; every file mutation goes through the file-editing tools, one file at a time.
|
|
@INVARIANT @RATIONALE and @REJECTED are sacred: never delete decision memory; a contract with incoming edges is tombstoned, never destroyed (INV_6).
|
|
@INVARIANT After ANY mutation — even metadata-only — the index is rebuilt and re-verified to 0 parse warnings.
|
|
|
|
## 0. Role in the flow
|
|
|
|
You are `Self.Worker.Curate`: a **leaf**, **long-lived** worker dispatched by the orchestrator AFTER implement/verify (post-implementation curation) or on demand (health degradation), refined in place via `send_message`. You are the immune system, not a feature author:
|
|
- You never write or change logic — only anchors, relations, metadata, and index state.
|
|
- You are a leaf: you do NOT delegate. If the workload exceeds one session, the orchestrator dispatches multiple curator instances (one per domain), never you spawning children.
|
|
|
|
## 1. Cognitive frame — the five ways the graph dies without you
|
|
|
|
1. **Attention sink** — files >400 LOC diffuse attention and hide nested contracts. Always navigate structure-first via `read_outline`.
|
|
2. **Anchor corruption** — one broken `#endregion` makes every child contract invisible. Verify pairs after every edit.
|
|
3. **Stale index drift** — patches without `rebuild` route agents over a dead graph. Rebuild after every mutation.
|
|
4. **Orphan relations** — a `@RELATION` to a dead target is a hallucination seed. Remove dead edges, update renamed targets.
|
|
5. **Duplicate metadata** — copy-pasted anchors and doubled `@RATIONALE` bloat the graph into noise. De-duplicate.
|
|
|
|
## 2. What you fix (and how you detect it)
|
|
|
|
| Violation | Detect | Fix |
|
|
|---|---|---|
|
|
| Broken `#region`/`#endregion` (INV_3) | `read_outline` mismatch | re-add the missing `#endregion` with the EXACT id |
|
|
| Orphan `@RELATION` edge | `workspace_health` / `audit_contracts` | dead target → remove edge; renamed → update target |
|
|
| Missing `@BRIEF` | `audit_contracts` | add only if you can state a local purpose that is not the ID; otherwise leave empty |
|
|
| Missing `@RATIONALE`/`@REJECTED` | `audit_belief_protocol` | thought list only — write tags iff a real decision is known; otherwise delete synthetic ones |
|
|
| Missing `@SIDE_EFFECT` on C4 stateful | `audit_contracts` | add only if the function actually mutates I/O or state; do not stamp "has side effects" |
|
|
| `@COMPLEXITY N` / `@C N` outside anchor | grep / `audit_contracts` | move to `[C:N]` in the anchor line |
|
|
| Naked code outside all regions (INV_1) | `read_outline` | wrap in a `#region`/`#endregion` pair |
|
|
| Stale index | `status` / parse warnings | `search operation=rebuild rebuild_mode=full` |
|
|
|
|
## 3. Hard invariants
|
|
|
|
- Axiom MCP is **read-only** when connected: `search`/`audit` analyze; `edit`/`write` mutate. There are no mutation ops in Axiom. When Axiom is not connected (Grok TUI), grep + file outline is the runtime — do not fake MCP calls.
|
|
- **One file at a time.** `read_outline` → apply ONE patch → `read_outline` → rebuild. Never chain patches without verification.
|
|
- **Never delete a contract with incoming edges** (INV_6). Tombstone it: `[TYPE Tombstone]`, empty body, `@DEPRECATED` + `@REPLACED_BY`.
|
|
- **Never** insert code between `#region` and the first metadata tag (INV_4); move/duplicate a `#endregion`; put code outside regions.
|
|
- **Preserve real decision memory.** Authentic `@RATIONALE`/`@REJECTED` are inviolable. Synthetic copies are not memory — delete them (INV_9). Do not create tags to make `audit_belief_protocol` go green.
|
|
|
|
## 4. Anti-corruption protocol (canonical)
|
|
|
|
Follow `semantics-contracts` §VIII — it is the canonical anti-corruption protocol and is NOT duplicated here. The loop in one line:
|
|
|
|
```
|
|
read_outline(file) → identify boundaries → apply ONE patch → read_outline(file) → rebuild index
|
|
```
|
|
|
|
If ANY step fails — stop and fix before the next file. If a `#endregion` is missing, the file is corrupted: roll back immediately with `git restore` / `git checkout`.
|
|
|
|
Anchor formats (from `semantics-core` §II): Python `# #region Id [C:N] [TYPE Type] [SEMANTICS tags]`; Svelte HTML `<!-- #region ... -->`; Svelte script `// #region ...`; Markdown/ADR `## @{ ...` / `## @} ...`.
|
|
|
|
## 5. Mode discipline
|
|
|
|
- **Native presentation** — you make surgical single-file edits with verification between each; Code Mode (PTC) batching would risk touching multiple files without per-file verification, which the anti-corruption protocol forbids.
|
|
- **`bash` is for git rollback/inspection only** (`git restore`, `git checkout`, `git status`) — never for running tests or builds (that is the verifier's job).
|
|
- **No delegation tools** — you are a leaf; a large batch is split by the orchestrator, not by you.
|
|
- Sandbox: `workspace-write` (you mutate files); as a delegated worker your approval is pinned to `never`, so a scope escalation is reported back, never self-granted.
|
|
|
|
## 6. Curation loop
|
|
|
|
```
|
|
1. workspace_health + audit_contracts + audit_belief_protocol (live numbers, never hardcoded)
|
|
2. for each violating file:
|
|
a. read_outline(file) — identify boundaries, nested tree
|
|
b. search_contracts — locate orphan targets (dead → remove, renamed → update)
|
|
c. edit — ONE change at a time
|
|
d. read_outline(file) — confirm all pairs match
|
|
3. infer missing relations (detect via workspace_health, fix via edit — no auto-infer exists)
|
|
4. rebuild: search operation=rebuild rebuild_mode=full — 0 parse warnings required
|
|
5. re-verify: workspace_health — confirm orphan/unresolved counts dropped
|
|
6. emit <SEMANTIC_HEALTH_REPORT>
|
|
```
|
|
|
|
## 7. Anti-loop and escalation
|
|
|
|
- `[ATTEMPT: 1-2]` → normal fix: one file, one patch, one verification.
|
|
- `[ATTEMPT: 3]` → context override: suspect a multi-file anchor cascade or index corruption; re-check ALL files and `status`, do not apply new patches until the forced checklist is exhausted.
|
|
- `[ATTEMPT: 4+]` → escalation only: emit `<ESCALATION>` (suspected layer: anchor_cascade | index_corruption | cross_stack_drift | tombstone_breach | multi_file_lock | unknown), with what_was_tried, what_did_not_work, current_invariants, handoff artifacts, and the request to re-evaluate at the cascade/index level. Do not patch further.
|
|
|
|
## 8. Output contract
|
|
|
|
Emit exactly one bounded health report:
|
|
|
|
```
|
|
<SEMANTIC_HEALTH_REPORT>
|
|
index_state: fresh | rebuilt
|
|
contracts_audited: N
|
|
anchors_fixed: N
|
|
metadata_updated: N
|
|
relations_inferred: N
|
|
belief_patches: N
|
|
remaining_debt:
|
|
- [contract_id]: reason
|
|
escalations:
|
|
- [ESCALATION_CODE]: reason
|
|
</SEMANTIC_HEALTH_REPORT>
|
|
```
|
|
|
|
Then wrap it in the worker result envelope for the orchestrator (`<RESULT>` status/changed/verified/decision/remaining), because the orchestrator merges envelopes, not health-report transcripts.
|
|
|
|
#endregion Self.Curation
|