llmosafe 0.6.2

Safety-critical cognitive safety library for AI agents. 4-tier architecture (Resource Body, Kernel, Working Memory, Sifter) with formal verification primitives, detection layer, and integration primitives.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# Agent Rules — llmosafe

## DNA vs RNA

Human-written documentation is **DNA** — structural ground truth. AI-generated summaries are **RNA** — inference calibrated against DNA. Never confuse them.

| Artifact | Who | Rule |
|----------|-----|------|
| `///` / `/** */` doc comments | Operator | **Never AI-modified.** Structural ground truth. |
| `//!` module docs | Operator | **Never AI-modified.** |
| `//` / `#` inline comments | Operator | **Never AI-modified.** Intent annotations. |
| `semantic_summary` field | Subagent | **RNA.** Regenerated each commit. Calibrated by DNA. |

| Language | Doc Comment | Module Doc | Inline | RNA Field |
|----------|------------|------------|--------|-----------|
| Rust | `///` | `//!` | `//` | `semantic_summary` |
| Python | `"""` (docstring) | `"""` (module) | `#` | `semantic_summary` |

**Rule:** DNA is the calibration layer. RNA is the inference layer. AI writes to `.annotations/` only — never to source doc comments.

---

## Subagent Annotation Pipeline

When annotations are needed, dispatch subagents in **waves** ordered by dependency (leaf → hub). Each wave's rejections feed the next wave's constraints.

### Rules

1. **Read, don't write.** Subagent reads its target entity + full dependency cluster (callers, callees, trait impls). Writes annotation proposals only — never source.
2. **Evidence required.** Every proposal must cite a line number in the code. No evidence → delete.
3. **Banned words.** Never use: `orchestrates`, `enables`, `facilitates`, `empowers`, `scalable`, `robust`, `architecture`. Describe WHAT code does, never WHY.
4. **Human gate.** Read `.annotations/` → approve/reject/edit → apply approved only. No path from proposal to DNA without operator approval.
5. **Rejection = constraint.** Rejected proposals become `DO NOT` constraints injected into the next wave's subagent prompts. The failure library grows monotonically — never remove entries, only add.

### Wave Ordering (leaf → hub)

1. Foundation types (`Synapse`, `CognitiveEntropy`, `BiasBreakdown`, `KernelError`)
2. Sifter + keyword lists
3. Detection layer (`RepetitionDetector`, `DriftDetector`, etc.)
4. Working memory
5. Kernel + reasoning loop
6. Resource body
7. Integration layer + EscalationPolicy
8. C-ABI + Python bindings

### Dispatch Format

```
[ROLE] Code Cartographer — maps WHAT code does, not WHAT it means.
[CONTEXT] target entity + callee signatures + caller context + existing comments.
[BANNED] inventing purpose, architecture claims, cross-file claims without evidence.
[OUTPUT] .annotations/[file].yaml with proposals + evidence line numbers.
```

### Output Schema

```yaml
# .annotations/llmosafe_kernel.yaml
file: src/llmosafe_kernel.rs
proposals:
  - target: "Synapse::validate (line 327)"
    semantic_summary: "Rejects synapse if bias detected or entropy exceeds stability threshold (1000)."
    evidence: [327, 328, 331]
    confidence: high
    DO_NOT:
      - "Do not claim validate() ensures surprise bounds — it doesn't check surprise."
      - "Do not describe this as 'orchestrating' or 'enabling' — it returns Result."
```

---

## Cross-Module Invariant Tracing (CMIT)

All future work must respect invariants defined in `invariants.toml`. Compound bugs live at boundaries — tests that only check final output cannot catch them. Every change that crosses a tier boundary must:

1. Check the relevant invariant in `invariants.toml`
2. Add or update a cross-module test in `tests/cross_module_invariants.rs`
3. Verify shadow validators fire in `#[cfg(debug_assertions)]` builds

---

## Bent Pyramid — 3-Strike Rule

If the same module boundary fails 3 times:
1. **Note** the pattern (not the instance)
2. **Redesign** the boundary contract
3. **Build again** with the redesign

No fourth patch at the same boundary. Escalate with evidence.

---

## Banned Patterns

| Pattern | Why |
|---------|-----|
| Writing doc comments without operator approval | DNA violation |
| Using banned words (`orchestrates`, `enables`, etc.) | Noise that hides behavior |
| Patching the same boundary 4+ times | Bent Pyramid violation |
| Adding code without a CMIT invariant check | Compound bug risk |
| Deleting entries from rejection/DO_NOT library | History loss |