refactor of repo

docs/rfcs/RFC-0007-Delegating-Router.md

@@ -0,0 +1,18 @@
+# RFC-0007: Delegating Router Primitive
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Invariant
+
+A router MUST NOT emit user-visible output unless it delegated to a
+child session and returns child output (verbatim or bounded wrapper).
+
+## Enforcement
+
+Use capability gating + `emit_guarded` (RFC-0010) validated against the
+Event Ledger (RFC-0009).
+
+## Output rules
+
+Router may prepend exactly one bounded line:
+`Delegating to <agent> because <reason>.` Max 240 chars.

docs/rfcs/RFC-0008-Capability-Guard-Framework.md

@@ -0,0 +1,14 @@
+# RFC-0008: Capability & Guard Framework
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Principle
+
+Control plane is deterministic. Privileged actions require explicit
+capabilities and guards that validate structured evidence (ledger
+events), not prompt text.
+
+## Guarded actions
+
+-   session_spawn (RFC-0011)
+-   emit_guarded (RFC-0010)

docs/rfcs/RFC-0009-Event-Ledger-Primitive.md

@@ -0,0 +1,15 @@
+# RFC-0009: Event Ledger Primitive
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Properties
+
+-   Append-only
+-   Hash-chained per stream
+-   Schema-validated
+-   Tamper-evident
+-   Supports proof construction for policy enforcement
+
+## Envelope
+
+Each event includes: id, ts, stream_id, type, body, prev_hash, hash.

docs/rfcs/RFC-0010-Guarded-Emit-Syscall.md

@@ -0,0 +1,13 @@
+# RFC-0010: Guarded Emit Syscall
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Signature
+
+emit_guarded(caller_session_id, request_id, output, proof_ref) -\>
+ok\|error
+
+## Enforcement
+
+Validates must-delegate invariant (RFC-0007) using ledger evidence
+(RFC-0009). Rejects output not derived from child output.

docs/rfcs/RFC-0011-Session-Spawn-Primitive.md

@@ -0,0 +1,36 @@
+# RFC-0011: Session Spawn Primitive
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Summary
+
+Defines a deterministic syscall to spawn a child cognitive session from
+a control-plane supervisor/router.
+
+## API
+
+`session_spawn(parent_session_id, request_id, target_agent, payload) -> child_session_id`
+
+## Preconditions
+
+-   Caller has `cap.session.spawn`.
+-   Payload is recorded (or hashed) for auditability.
+-   Spawn emits a `session_spawn` ledger event (RFC-0009).
+
+## Postconditions
+
+-   A child session exists with its own stream_id.
+-   Parent stream contains `session_spawn` pointing to child session_id.
+-   Child stream begins with a genesis event referencing parent spawn
+    context.
+
+## Security
+
+-   Child inherits only explicit capabilities (no ambient authority).
+-   Parent cannot read child internal chain-of-thought unless explicitly
+    granted (separate capability).
+
+## Observability
+
+Record: - target_agent - payload_hash - resource limits (if any) -
+parent/child linkage

docs/rfcs/RFC-0012-Deterministic-Retry-Controller.md

@@ -0,0 +1,36 @@
+# RFC-0012: Deterministic Retry Controller
+
+**Status:** Draft \| **Updated:** 2026-02-17
+
+## Summary
+
+Defines a bounded, deterministic retry mechanism for control-plane
+policy violations and transient failures.
+
+## Goals
+
+-   Bounded retries (no infinite loops)
+-   Transparent ledger recording
+-   Clear failure modes
+
+## API (conceptual)
+
+`retry_controller(run_id, max_attempts, policy) -> result`
+
+## Reference Policy: must-delegate
+
+-   Attempt 1: run router normally
+-   If emit_guarded rejects with POLICY_VIOLATION_MUST_DELEGATE:
+    -   record `policy_violation` + `retry_scheduled`
+    -   rerun router in **strict mode** (no free-form output; must spawn
+        immediately)
+-   Attempt 2: if violation repeats:
+    -   fail closed with deterministic error message
+    -   record `run_failed`
+
+## Ledger Events
+
+-   retry_scheduled
+-   retry_started
+-   retry_exhausted
+-   run_failed