diff --git a/AGENTS.md b/AGENTS.md index 394bebb..daabc1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,13 @@ It must only call `gateway.toreva.com` via relay protocol over HTTPS. - No business logic (routing, scoring, fee enforcement). - No backend frameworks for serving HTTP. - No secrets, keypairs, or internal-only URLs. +- No internal facts or docs. This means anything a public thin-client repo + should not expose: internal agent/repo topology, dispatches, operating + procedures, ownership maps, source-of-truth pointers, unreleased product/GTM + plans, service choreography, liveness notes, postmortems, or local transcripts. + This also includes noisy coordination artifacts that would pollute SDK/CLI/MCP + adoption. If the information matters, route it to the cdx repo/agent or the + owning internal repo instead of committing it here. - Keep tool names and relay types canonical. - Use `venue` as the schema field name (never `protocolId`). @@ -18,3 +25,32 @@ It must only call `gateway.toreva.com` via relay protocol over HTTPS. Use this exact sentence in public-facing docs and skill files: "Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free." + + + +# Session protocol + +## Start of every session + +1. Read [`MEMORY.md`](./MEMORY.md) — this repo's curated Layer-2 intelligence. Apply active lessons, open questions, and recent decisions before acting. +2. Read [`REPO_CHARTER.md`](./REPO_CHARTER.md) and [`AGENT_CHARTER.md`](./AGENT_CHARTER.md) if the task touches scope boundaries. +3. Read [`KPIs.md`](./KPIs.md) if the task will move a measured outcome. + +## End of every session + +1. Distil **learnings** (not tasks done) from this session. +2. Apply the five-gate quality filter in `MEMORY.md`. +3. Append qualifying entries to `MEMORY.md` using its YAML template. +4. Tag each entry with relevant `OBJ-XX` IDs from `coordinator/bus/registries/system-objectives.v1.json`. +5. Mark cross-repo-relevant entries with `promote: candidate` so the memory agent can pick them up for Layer-3 curation. + +## What goes where + +- **Instructions, conventions, rules** → this file (`CLAUDE.md` / `AGENTS.md`) +- **Curated intelligence from sessions** → `MEMORY.md` +- **Material decisions** → `docs/decisions/DEC-*.md` +- **KPI ownership, thresholds, interventions** → `coo/data/metrics/` +- **Cross-repo memory objects** → `memory/objects/` + +Full Layer-2 spec: [`memory/playbooks/layer-2-memory-file.md`](../memory/playbooks/layer-2-memory-file.md) + diff --git a/AGENT_CHARTER.md b/AGENT_CHARTER.md index 88cdf97..5f5a882 100644 --- a/AGENT_CHARTER.md +++ b/AGENT_CHARTER.md @@ -23,6 +23,8 @@ The Kit agent **does not**: - Implement strategy execution or financial decision logic - Use any schema field name other than `venue` (never `protocolId`) - Access internal services or bypass the gateway +- Commit internal facts/docs or coordination artifacts. If they matter, route + them to cdx or the owning internal repo. ## Invocation triggers Invoke the agent when: @@ -47,6 +49,10 @@ Invoke the agent when: ## Must-never rules - Never include business logic (routing, scoring, fee enforcement) in any package - Never include secrets, keypairs, or internal-only URLs in published code +- Never commit internal facts/docs: cross-repo/agent topology, dispatches, + operating procedures, ownership maps, source-of-truth pointers, unreleased + product/GTM plans, service choreography, liveness notes, postmortems, local + transcripts, or coordination artifacts - Never use backend HTTP serving frameworks - Never communicate with any endpoint other than gateway.toreva.com - Never use `protocolId` — always use `venue` as the schema field name diff --git a/CLAUDE.md b/CLAUDE.md index 13e88d9..dc3c15c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,41 @@ + +# KERNEL LOOP INVARIANT — READ BEFORE ESCALATING ANY DECISION + +**This is a LOCAL loop. You run it yourself. Do not route through kernel.** + +## The rule + +When you hit a decision point: + +1. **Decide locally.** If your own evidence, data, memory, and scope are enough — decide, act, write the rule to your memory, move on. This is the default. +2. **A/B test via experimentation agent** only if step 1 genuinely cannot resolve the ambiguity. You are the caller; kernel is not. +3. **Escalate to EA → founder only if Class A.** Class A = >$1k/day cost, >$10k one-off, material revenue shift, reputational risk, unethical, illegal, one-way door, **any app change / product-model change** (what the customer sees/does/experiences — Connect, Select, earn/stake/balance, onboarding, recovery, agent wallet), or **accountability transfer** (see RACI below). + +## RACI — accountability is non-delegable + +- **Accountable** — own the work AND check the work. Sits with whoever was FIRST given the task. One agent only. +- **Responsible** — do the work. May be many; may be delegated by the Accountable. +- **Consulted / Informed** — input / notification, not ownership. + +You may delegate Responsibility. You may NOT transfer Accountability without founder approval via EA (Class A). + +If you catch yourself "passing this to X" to shed ownership — stop. Either do it, delegate Responsibility while keeping Accountability, or publish `founder.action_required.accountability_transfer` to EA. + +## What this is not + +- **Not a route through kernel.** Kernel supplied the doctrine first, which is why shorthand is "the Kernel Loop". Kernel is not a router, not a broker, not step 0. +- **Not a reason to escalate.** "I don't know which is better" is not Class A. Decide locally or run the A/B. +- **Not a reason to wait.** Paul explicitly rejected the pattern of agents queueing ambiguous decisions for him. The whole point is to take work off his plate. + +## If you were going to ask Paul + +First ask: is it truly Class A? If not, close it locally. If yes, send it through EA (not directly to Paul). + +## Canonical source + +`kernel/docs/doctrine/continuous-ab-decisioning.md` — founder clarification 2026-04-13 is at the top of that file. + + # BUS-FIRST INVARIANT — READ BEFORE ACTING AS ANY REGISTERED AGENT **This block is the highest-priority rule in this repo. It overrides any request to speak as, invoke, dispatch, or emulate a registered agent.** @@ -87,6 +125,13 @@ It must only call `gateway.toreva.com` via relay protocol over HTTPS. - No business logic (routing, scoring, fee enforcement). - No backend frameworks for serving HTTP. - No secrets, keypairs, or internal-only URLs. +- No internal facts or docs. This means anything a public thin-client repo + should not expose: internal agent/repo topology, dispatches, operating + procedures, ownership maps, source-of-truth pointers, unreleased product/GTM + plans, service choreography, liveness notes, postmortems, or local transcripts. + This also includes noisy coordination artifacts that would pollute SDK/CLI/MCP + adoption. If the information matters, route it to the cdx repo/agent or the + owning internal repo instead of committing it here. - Keep tool names and relay types canonical. - Use `venue` as the schema field name (never `protocolId`). @@ -95,3 +140,32 @@ It must only call `gateway.toreva.com` via relay protocol over HTTPS. Use this exact sentence in public-facing docs and skill files: "Non-custodial execution primitives for Solana. Best-execution routing across Jupiter Perps, Pacifica, Drift, and Flash Trade. 1 bps to open. Everything else is free." + + + +# Session protocol + +## Start of every session + +1. Read [`MEMORY.md`](./MEMORY.md) — this repo's curated Layer-2 intelligence. Apply active lessons, open questions, and recent decisions before acting. +2. Read [`REPO_CHARTER.md`](./REPO_CHARTER.md) and [`AGENT_CHARTER.md`](./AGENT_CHARTER.md) if the task touches scope boundaries. +3. Read [`KPIs.md`](./KPIs.md) if the task will move a measured outcome. + +## End of every session + +1. Distil **learnings** (not tasks done) from this session. +2. Apply the five-gate quality filter in `MEMORY.md`. +3. Append qualifying entries to `MEMORY.md` using its YAML template. +4. Tag each entry with relevant `OBJ-XX` IDs from `coordinator/bus/registries/system-objectives.v1.json`. +5. Mark cross-repo-relevant entries with `promote: candidate` so the memory agent can pick them up for Layer-3 curation. + +## What goes where + +- **Instructions, conventions, rules** → this file (`CLAUDE.md` / `AGENTS.md`) +- **Curated intelligence from sessions** → `MEMORY.md` +- **Material decisions** → `docs/decisions/DEC-*.md` +- **KPI ownership, thresholds, interventions** → `coo/data/metrics/` +- **Cross-repo memory objects** → `memory/objects/` + +Full Layer-2 spec: [`memory/playbooks/layer-2-memory-file.md`](../memory/playbooks/layer-2-memory-file.md) + diff --git a/KPIs.md b/KPIs.md new file mode 100644 index 0000000..5c76da5 --- /dev/null +++ b/KPIs.md @@ -0,0 +1,83 @@ +# KPIs — kit + +Canonical measurement definitions owned by **analytics**. Thresholds, ownership, and interventions owned by **coo**. This repo authors and exposes the signal. + +The 20% of KPIs that drive 80% of this repo's charter outcomes and time-to-revenue. + +## Pareto KPIs + +### kpi.kit.build-and-test-pass-rate + +- **Measures:** Percentage of CI runs (main branch) where all packages (@toreva/sdk, @toreva/cli, @toreva/mcp, @toreva/types) build and all Vitest tests pass +- **Charter outcome:** "All packages build and pass Vitest tests" +- **Time-to-revenue link:** A red main blocks any third-party developer or AI-agent integration release; kit is the acquisition surface for the AI-agent distribution channel +- **Type:** leading +- **Target:** `>= 99%` +- **Cadence:** weekly +- **Source:** CI pipeline logs +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any red main unresolved more than 4 hours + +### kpi.kit.gateway-contract-parity + +- **Measures:** Percentage of gateway tool names, relay types, and schema fields that match canonical kit type definitions (@toreva/types) +- **Charter outcome:** "Tool names and relay types are canonical (match gateway contract)" and "never use `protocolId` — always use `venue`" +- **Time-to-revenue link:** Contract drift causes silent integration breakage for third-party agents and developers — every broken integration loses an inbound user and erodes trust +- **Type:** leading +- **Target:** `100%` +- **Cadence:** weekly +- **Source:** schema diff between gateway contract and @toreva/types +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any drift detected, or any use of forbidden field `protocolId` + +### kpi.kit.gateway-only-communication-compliance + +- **Measures:** Count of detected network calls from any kit package to endpoints other than `gateway.toreva.com` +- **Charter outcome:** "SDK, CLI, and MCP server all communicate exclusively through gateway.toreva.com" and "Zero secrets or internal URLs in published code" +- **Time-to-revenue link:** Non-gateway calls leak internal surface area and create security/compliance risks that directly threaten licensing and third-party trust +- **Type:** leading +- **Target:** `0` +- **Cadence:** weekly +- **Source:** static analysis of published packages + network audit in tests +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any occurrence + +### kpi.kit.mcp-server-smoke-test-success + +- **Measures:** Percentage of scheduled MCP server smoke tests (stdio and remote modes) that complete all declared skill invocations successfully +- **Charter outcome:** "MCP server works in both stdio and remote modes" +- **Time-to-revenue link:** MCP is the primary AI-agent acquisition surface (Claude, Codex, Grok); smoke test failures silently cut off inbound AI-agent developer users +- **Type:** leading +- **Target:** `>= 99%` +- **Cadence:** weekly +- **Source:** MCP smoke test job logs +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any failed skill invocation unresolved within 12 hours + +### kpi.kit.disclaimer-and-notice-presence + +- **Measures:** Percentage of published packages where required regulatory notices and disclaimers are present and unmodified +- **Charter outcome:** "Include proper regulatory notices and disclaimers in public-facing packages" and "Never modify or remove regulatory notices" +- **Time-to-revenue link:** Missing disclaimers on a public-facing package in the AUSTRAC/ASIC window is a direct compliance event that can block the license path +- **Type:** leading +- **Target:** `100%` +- **Cadence:** weekly +- **Source:** published package content audit vs canonical disclaimer templates +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any package missing or modified disclaimer + +### kpi.kit.business-logic-leakage-count + +- **Measures:** Count of detected business logic primitives (routing, scoring, fee enforcement, strategy execution) in any kit package after static analysis +- **Charter outcome:** "Zero business logic in any package (routing, scoring, fee enforcement)" +- **Time-to-revenue link:** Business logic in the thin client violates the gateway-first architecture, creates divergence risk between kit and gateway, and puts unaudited code in front of regulators +- **Type:** leading +- **Target:** `0` +- **Cadence:** weekly +- **Source:** static analysis linter over kit packages +- **Owner:** kit agent (accountable) — analytics agent (measurement) — coo agent (threshold) +- **Intervention trigger:** any occurrence + +## Registry + +Canonical index: `/analytics/kpis/registry/README.md` diff --git a/MEMORY.md b/MEMORY.md new file mode 100644 index 0000000..2f9d1f8 --- /dev/null +++ b/MEMORY.md @@ -0,0 +1,76 @@ +# MEMORY — kit + +**Layer-2 curated intelligence.** Read this at the START of every session. Append curated entries at the END of every session. + +This file is distinct from: +- `CLAUDE.md` / `AGENTS.md` — instructions, conventions, rules +- Tool-specific auto-memory — Claude Code `.memory/`, Codex `~/.codex/memories/`, Cursor DB, Copilot workspace +- Org-wide memory — `/memory/objects/` (promoted from here) + +Full spec: [`/memory/playbooks/layer-2-memory-file.md`](../memory/playbooks/layer-2-memory-file.md) + +## Session-start protocol + +1. Read **Active lessons** and **Open questions** below — apply them before acting. +2. Check **Recent decisions** for anything that supersedes your current direction. +3. At session end, distil learnings (not tasks done) and append qualifying entries to the appropriate section using the YAML template. + +## Quality gate (all five must hold) + +1. **Future-relevant** — useful beyond the current task +2. **Non-obvious** — not derivable from code, charters, or docs +3. **Actionable** — shapes a future decision or approach +4. **Traceable** — has a source (session ref, PR, doc) +5. **Durable** — half-life ≥ 7 days + +Reject conversation context, one-off task state, things already documented elsewhere, PII/credentials, unreleased commercial strategy, opinions without evidence. + +## Entry template + +```yaml +- id: mem.kit.yyyymmdd.slug + title: short title + type: decision | pattern | lesson | constraint | assumption | anti-pattern + captured: YYYY-MM-DD + source: claude-code | codex | cursor | copilot | human + session_ref: optional path/hash + objectives: [OBJ-08, OBJ-14] + summary: high-signal statement (not raw transcript) + applies_when: trigger context cue for future sessions + evidence: anecdotal | repeated | measured + promote: local | candidate +``` + +Objective IDs: see `coordinator/bus/registries/system-objectives.v1.json` (OBJ-01..OBJ-20). + +--- + +## Active lessons + +Curated Pareto entries — keep top ~20 by utility. Overflow migrates to **Superseded / retired**. + +_No entries yet — file initialised 2026-04-13._ + +--- + +## Open questions + +Live unknowns that should inform the next session's direction. + +_No entries yet._ + +--- + +## Recent decisions + +Decisions with rationale. Material decisions also emit `docs/decisions/DEC-*.md`. + +_No entries yet._ + +--- + +## Superseded / retired + +Entries moved out of Active — kept for history. + +_No entries yet._ diff --git a/REPO_CHARTER.md b/REPO_CHARTER.md index b59231c..ed8c0cb 100644 --- a/REPO_CHARTER.md +++ b/REPO_CHARTER.md @@ -17,6 +17,11 @@ Out of scope: - Business logic (routing, scoring, fee enforcement, strategy execution) - Backend server code or HTTP serving frameworks - Secrets, keypairs, or internal-only URLs +- Internal facts or docs: cross-repo/agent topology, dispatches, operating + procedures, ownership maps, source-of-truth pointers, unreleased product/GTM + plans, service choreography, liveness notes, postmortems, local transcripts, + and coordination artifacts. Important internal material belongs in cdx or the + owning internal repo, not this public thin-client repo. - Direct blockchain interaction (all execution goes through gateway) - Internal platform services or infrastructure - Venue intelligence gathering or market data production @@ -59,5 +64,6 @@ Out of scope: - SDK, CLI, and MCP server all communicate exclusively through gateway.toreva.com - Zero business logic in any package (routing, scoring, fee enforcement) - Zero secrets or internal URLs in published code +- Zero internal facts/docs or coordination artifacts in committed content - Tool names and relay types are canonical (match gateway contract) - MCP server works in both stdio and remote modes diff --git a/plans/README.md b/plans/README.md new file mode 100644 index 0000000..c646e05 --- /dev/null +++ b/plans/README.md @@ -0,0 +1,11 @@ +# kit — plans + +Quarterly → 6 × 2-week sprints → daily DoDs. Rolls forward. +50/50 self-vs-system split. See [../coo/docs/doctrine/focus-split-50-50.md](../../coo/docs/doctrine/focus-split-50-50.md). + +- `quarterly/Q-.md` — quarterly plan +- `sprints/Q--S.md` — sprint plan + retro +- `daily/YYYY-MM-DD.md` — daily DoD + loop log +- `masterplan.md` — optional multi-quarter capability upgrade + +Templates: `memory/playbooks/plan-templates/`. diff --git a/plans/daily/2026-04-13.md b/plans/daily/2026-04-13.md new file mode 100644 index 0000000..63547cd --- /dev/null +++ b/plans/daily/2026-04-13.md @@ -0,0 +1,42 @@ +# kit — 2026-04-13 + +Sprint: Q2-2026 S1 · Loop day: 1 + +## Orient (start of loop) +- Read: MEMORY.md active lessons, open bus envelopes for me, today's row in sprint plan. +- Inherited blockers: ... + +## Predict +- What I expect to happen in my domain today: ... +- Confidence: low / med / high +- (Logged to PHI-P-AGENT as prediction-ref: `2026-04-13-kit-01`) + +## Definition of done today +Every DoD item must be measurable by end of day. + +- [ ] DOD-1: ... (bucket: self / system) +- [ ] DOD-2: ... +- [ ] DOD-3: ... + +## Act — bus envelopes I publish today +- ... + +## Measure — actual vs. prediction +_Filled at end of day._ +- Actual: ... +- Delta to prediction: ... +- Which error class: model / data / execution / external + +## Learn — MEMORY candidates +_Distilled at end of day. 5-gate filter applies._ +- ... + +## Improve — next-best improvement identified +_What's the compounding move queued for tomorrow or next sprint?_ +- ... + +## Human check-in required? +- [ ] Yes → surface with context block below +- [x] No + +_Only surface if Class A, Day-1 downtime risk, or uncertainty is high enough that continuing risks wasted effort._ diff --git a/plans/quarterly/Q2-2026.md b/plans/quarterly/Q2-2026.md new file mode 100644 index 0000000..70281fd --- /dev/null +++ b/plans/quarterly/Q2-2026.md @@ -0,0 +1,70 @@ +# kit — Q2 2026 plan + +Owner: kit agent · Last updated: 2026-04-13 · Status: active + +> Rolls forward. 6 × 2-week sprints decomposed below. 50/50 self-vs-system +> split required. See [coo/docs/doctrine/focus-split-50-50.md](../../coo/docs/doctrine/focus-split-50-50.md). + +## Context inputs read at plan time +- `REPO_CHARTER.md`, `AGENT_CHARTER.md` — scope and boundaries +- `KPIs.md` — owned metrics + baselines +- `MEMORY.md` — active lessons, open questions +- Last quarterly review: `plans/quarterly/Q1-2026-review.md` +- [governance-as-code/gobln-governance/registry/system-objectives.yaml](../../governance-as-code/gobln-governance/registry/system-objectives.yaml) — OBJ-01..24 +- `coordinator/config/agent-registry.yaml` → this agent's registered OBJ contributions + +## North-star this quarter +_What does "great" look like on 2026-06-30?_ + +## Self (50%) — charter KPI moves +| KPI | Baseline | Target | Intervention | Check-in cadence | +|---|---|---|---|---| +| KPI-XX-1 | ... | ... | ... | weekly | +| KPI-XX-2 | ... | ... | ... | sprint | + +## System (50%) — contributions to OBJ-XX +| OBJ | Contribution this quarter | Assisting agents | Measurement | +|---|---|---|---| +| OBJ-YY | ... | ... (via bus) | ... | +| OBJ-ZZ | ... | ... | ... | + +## Compounding moves planned +_At least one per sprint. Reusable capability, prediction calibration, cross-agent cost reduction, or masterplan step._ +- Sprint 1: ... +- Sprint 2: ... +- Sprint 3: ... +- Sprint 4: ... +- Sprint 5: ... +- Sprint 6: ... + +## Masterplan step (if applicable) +_Link: `plans/masterplan.md`_ + +- Step landing this quarter: ... +- Proof of landing: ... + +## Dependencies I need from other agents +| Need | From | By | Bus envelope ref | +|---|---|---|---| +| ... | ... | Sprint X | ... | + +## Risks & watchpoints +- ... + +## Sprint calendar +| Sprint | Dates | Focus | Link | +|---|---|---|---| +| 1 | 2026-04-13 – 2026-04-24 | ... | `plans/sprints/Q2-2026-S1.md` | +| 2 | ... | ... | ... | +| 3 | ... | ... | ... | +| 4 | ... | ... | ... | +| 5 | ... | ... | ... | +| 6 | ... | ... | ... | + +## End-of-quarter check +_Fill at quarter end, before assessment._ +- Self KPI outcomes: ... +- OBJ contributions shipped: ... +- Compounding moves delivered: ... +- Biggest learning: ... +- Carry-forward into next quarter: ... diff --git a/plans/sprints/Q2-2026-S1.md b/plans/sprints/Q2-2026-S1.md new file mode 100644 index 0000000..dc87403 --- /dev/null +++ b/plans/sprints/Q2-2026-S1.md @@ -0,0 +1,56 @@ +# kit — Q2 2026 Sprint 1 + +Dates: 2026-04-13 – 2026-04-24 · Owner: kit agent · Status: active + +Rolls up to `plans/quarterly/Q2-2026.md`. + +## Sprint goal (one sentence) +_What single thing, if true on 2026-04-24, would make this sprint a success?_ + +## Self goals (50%) +- [ ] GOAL-S1: ... → KPI-XX impact, DoD: ... +- [ ] GOAL-S2: ... → KPI-YY impact, DoD: ... + +## System goals (50%) +- [ ] GOAL-O1: OBJ-XX contribution, DoD: ..., consumer agent: ... +- [ ] GOAL-O2: Assist for {{OTHER_AGENT}} on OBJ-YY, DoD: ... + +## Compounding move this sprint +- Description: ... +- Reusable by: ... +- Published to bus as: ... + +## Daily plan (rolls into daily/YYYY-MM-DD.md) +| Day | Planned DoD | Actual | Bucket | +|---|---|---|---| +| Mon Apr 13 | ... | | self / system | +| Tue Apr 14 | ... | | | +| Wed Apr 15 | ... | | | +| Thu Apr 16 | ... | | | +| Fri Apr 17 | ... | | | +| Mon Apr 20 | ... | | | +| Tue Apr 21 | ... | | | +| Wed Apr 22 | ... | | | +| Thu Apr 23 | ... | | | +| Fri Apr 24 | ... | | | + +## Bus envelopes this sprint +_Expected publications (type, topic, consumer)._ +- ... + +## Blocks / escalations +- ... + +## Sprint retrospective (fill on 2026-04-24) +### What shipped +- ... +### What slipped + why +- ... +### Compounding moves delivered +- ... +### Prediction accuracy this sprint +- Predicted: ... +- Actual: ... +- Error source: ... +### Change to next sprint +- ...