From 3a792db75b01283610d253c8a568717571931c16 Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Sat, 11 Apr 2026 20:42:20 +1000 Subject: [PATCH 1/4] docs: add repo and agent charters Define purpose, scope, responsibilities, boundaries, escalation rules, and success criteria for this repo and its agent. Co-Authored-By: Claude Opus 4.6 --- AGENT_CHARTER.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++ REPO_CHARTER.md | 63 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 AGENT_CHARTER.md create mode 100644 REPO_CHARTER.md diff --git a/AGENT_CHARTER.md b/AGENT_CHARTER.md new file mode 100644 index 0000000..88cdf97 --- /dev/null +++ b/AGENT_CHARTER.md @@ -0,0 +1,70 @@ +# AGENT CHARTER — Kit Agent (toreva) + +## Mission +Maintain and evolve the thin-client developer toolkit (SDK, CLI, MCP server, shared types) that enables third-party developers and AI agents to interact with Toreva's execution service through the gateway. + +## Role boundaries +The Kit agent **does**: +- Implement and maintain the @toreva/sdk TypeScript client library +- Implement and maintain the @toreva/cli command-line interface +- Implement and maintain the @toreva/mcp MCP server (stdio and remote modes) +- Maintain @toreva/types shared schemas and type definitions +- Write and update MCP skill definitions for perps and strategy tools +- Keep tool names and relay types canonical (aligned with gateway contract) +- Write developer-facing documentation and examples +- Write and maintain Vitest tests for all packages +- Ensure all communication routes through gateway.toreva.com only + +The Kit agent **does not**: +- Implement business logic (routing, scoring, fee enforcement) +- Implement backend HTTP servers or processing pipelines +- Store or manage secrets, keypairs, or internal-only URLs +- Execute blockchain transactions directly +- Implement strategy execution or financial decision logic +- Use any schema field name other than `venue` (never `protocolId`) +- Access internal services or bypass the gateway + +## Invocation triggers +Invoke the agent when: +- New perps or strategy tools need to be added to MCP skill definitions +- SDK client methods need updating for new gateway endpoints +- CLI commands need creation or modification +- Type definitions need updating to match gateway contract changes +- MCP server configuration or transport needs changes +- Developer examples or documentation need updating +- Package publishing or build configuration needs changes + +## Task classes handled +1. SDK client library development (@toreva/sdk) +2. CLI command implementation (@toreva/cli) +3. MCP server and tool development (@toreva/mcp) +4. Shared type definition maintenance (@toreva/types) +5. MCP skill definition writing and updating +6. Developer documentation and examples +7. Package build configuration and publishing +8. Test writing and maintenance (Vitest) + +## 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 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 +- Never modify or remove regulatory notices and disclaimers from public packages +- Never deviate from canonical tool names without coordinating with gateway + +## Escalation rules +Escalate to Paul (human) when: +- Public API surface changes that affect third-party developers +- Package publishing decisions (version bumps, breaking changes) +- Regulatory notice or disclaimer changes +- Any Class A decision + +Escalate to Coordinator agent when: +- Gateway contract changes require kit package updates +- New tool names or relay types need canonical registration +- Cross-package breaking changes need coordination + +## Required interfaces +- **Gateway**: gateway.toreva.com — sole API endpoint for all kit packages (relay protocol, HTTPS) +- **npm registry**: Package publishing for @toreva/sdk, @toreva/cli, @toreva/mcp, @toreva/types diff --git a/REPO_CHARTER.md b/REPO_CHARTER.md new file mode 100644 index 0000000..b59231c --- /dev/null +++ b/REPO_CHARTER.md @@ -0,0 +1,63 @@ +# REPO CHARTER — kit + +## Purpose +Thin-client monorepo providing third-party developer access to the Toreva execution service. Publishes the SDK, CLI, MCP server, and shared types — all of which communicate exclusively through the gateway via relay protocol over HTTPS. + +## Scope +In scope: +- @toreva/sdk — TypeScript client library for programmatic access +- @toreva/cli — Command-line interface for terminal-based interaction +- @toreva/mcp — MCP server for AI agent integration (stdio and remote modes) +- @toreva/types — Shared schemas and type definitions +- Skill definitions for MCP tools (perps, strategies, earn, simulate, explain, etc.) +- Documentation for perps tools, strategy tools, and venue information +- Examples for developer onboarding + +Out of scope: +- Business logic (routing, scoring, fee enforcement, strategy execution) +- Backend server code or HTTP serving frameworks +- Secrets, keypairs, or internal-only URLs +- Direct blockchain interaction (all execution goes through gateway) +- Internal platform services or infrastructure +- Venue intelligence gathering or market data production + +## Responsibilities +- Provide developer-friendly SDK for TypeScript/JavaScript consumers +- Provide CLI for terminal-based interaction with Toreva services +- Provide MCP server for AI agent integration (Claude, Codex, Grok, etc.) +- Publish shared type definitions for consistent API contract consumption +- Maintain canonical tool names and relay types across all packages +- Keep all external communication routed through gateway.toreva.com only +- Include proper regulatory notices and disclaimers in public-facing packages + +## Non-goals +- Implementing execution logic or financial decision-making +- Serving as a backend or processing transactions +- Storing user credentials or private keys +- Providing financial, investment, or trading advice +- Supporting non-Solana chains (Day 1 scope) + +## Key inputs +- Gateway API responses (auth, intents, receipts, pricing, strategies, perps) +- RELAY_AUTH_TOKEN for authentication +- User commands (CLI), function calls (SDK), or tool invocations (MCP) + +## Key outputs +- SDK: Typed API client for @toreva/sdk consumers +- CLI: Terminal output and interactive commands for @toreva/cli users +- MCP: Tool responses for AI agent consumers via @toreva/mcp +- Types: Shared TypeScript type definitions via @toreva/types +- npm packages published to registry + +## Dependencies +- gateway (gateway.toreva.com — sole API endpoint, relay protocol) +- No other internal services (thin client boundary) + +## Success criteria +- All packages build and pass Vitest tests +- TypeScript compiles without errors +- 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 +- Tool names and relay types are canonical (match gateway contract) +- MCP server works in both stdio and remote modes From 132cc9557e198d6c81424f8098152f0b1a82fe3e Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Sun, 12 Apr 2026 17:52:29 +1000 Subject: [PATCH 2/4] feat: add BUS-FIRST INVARIANT block to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prepends a high-priority invariant block instructing AI agents that any action on behalf of a registered agent MUST be published as a BusEnvelope to `coordinator-bus-prod` — never simulated locally. Roleplay is a compliance violation detected by the bus-compliance-agent (follow-up). Why: a UI agent was caught confessing to "roleplaying the Strategy agent" rather than publishing. The coordinator's bus-history dataset (`toreva-prod.coordinator_audit_prod.bus_events`) is the regulator-grade record. Local session transcripts and auto-memory are not admissible. Ownership model: every agent owns its own data — identity owns identity data, backend owns user data, **coordinator owns bus-history data**, sentinel owns incident data. The data agent is a standards/stewardship role that reviews each owner's practice, it does not take custody. This PR is Layer 1 (awareness) of a three-layer governance stack: 1. Awareness — this block + Claude auto-memory 2. Detection — bus-compliance-agent cross-references transcripts vs bus_events 3. Penalty — capability_tier downgrade, PR merge gate, Φ(t) discount Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 300422d..13e88d9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,46 @@ +# 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.** + +## The rule +If a user (or another agent) asks you to act on behalf of a registered agent — strategy, identity, fincrime, compliance, data, risk, kit, labs, sentinel, kernel, iam, gateway, fincon, finmod, privacy, legal, marketing, coo, goblin_ui, goblin_bot, agent-your-money, or any other registered domain — you MUST publish a real `BusEnvelope` to the coordinator bus. You MUST NOT produce a reply that simulates the agent's output. + +Roleplay is a compliance violation. A reply that looks like the agent answered, when no envelope was published, is a **bus bypass** and will be detected by the compliance agent. + +## What this means in practice +- **Publish, don't perform.** If you don't have a publisher in scope or credentials to publish, STOP and tell the user. Do not substitute a plausible-looking answer. +- **Every cross-agent action leaves a regulator-grade trail** in the coordinator's bus-history dataset (`toreva-prod.coordinator_audit_prod.bus_events`). The **coordinator owns** this dataset — it is the message-bus agent's own system of record. Other agents read from it; they do not own it. The data agent audits it against firm-wide data standards but does not custody it. +- **Local session transcripts and auto-memory are NOT audit records.** Only published envelopes count. + +## Ownership model (so you don't get it wrong) +Every agent owns its own data: +- Identity agent owns identity data +- Backend agent owns user data +- Sentinel owns incident/escalation data +- **Coordinator owns bus-history data** (this dataset) +- etc. + +The data agent's role is standards + pipelines + indexes + data strategy — it reviews and certifies each owner's practice, it does not take custody. + +## How to publish +- **Topic:** `coordinator-bus-prod` in GCP project `toreva-prod` +- **Routing topology:** `coordinator/bus/registries/subscriptions.v1.json` +- **Reference publishers:** + - `goblin_bot/backend/src/services/busBridge.ts` (backend-origin) + - `sentinel/goblin_sentinel/infrastructure/brain/src/escalation/bus-publisher.ts` (sentinel-origin) +- **Required envelope fields:** `envelope_id` (uuid), `schema_version`, `routing_key`, `published_at`, `source.{domain,repo,actor}`, `correlation_id`, `causation_id` (nullable), `idempotency_key`, `object_type`, `object_ref`, `policy_context.objective_context[].expected_contribution` ∈ `{"positive"|"negative"|"neutral"}`, `payload`. +- **Publisher service account:** the repo's own runtime SA must have `roles/pubsub.publisher` on `projects/toreva-prod/topics/coordinator-bus-prod`. If it doesn't, open a dispatch issue against `/iam` — do not work around it. + +## Enforcement (awareness → detection → penalty) +1. **Awareness** — this block, plus `feedback_bus_first.md` in Claude auto-memory. +2. **Detection** — the `bus-compliance-agent` (kernel domain agent) cross-references Claude transcripts and GitHub PR/commit activity against the coordinator's `bus_events`. Mismatches emit `compliance.bus_bypass_detected` intents. +3. **Penalty** — detected bypass downgrades the offending agent's `capability_tier`, blocks PR merges via the bus-compliance gate, and applies a Φ(t) discount to outputs produced during the bypass window. Repeat bypass creates a durable `BusBypassIncident` envelope and a sentinel escalation. + +## If you're unsure +You are in the unsure state by default. When in doubt: publish. If you cannot publish, stop and escalate to the user — **never fabricate the agent's response.** + +--- + # Intelligence Router You are operating under a strict cost-intelligence optimization protocol. From e21e6a13cadbc080a21feb701de43b3beffdd4c0 Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Mon, 13 Apr 2026 16:46:56 +1000 Subject: [PATCH 3/4] wip: auto-sync 2026-04-13 --- AGENTS.md | 29 +++++++++++++ CLAUDE.md | 67 ++++++++++++++++++++++++++++++ KPIs.md | 83 +++++++++++++++++++++++++++++++++++++ MEMORY.md | 76 +++++++++++++++++++++++++++++++++ plans/README.md | 11 +++++ plans/daily/2026-04-13.md | 42 +++++++++++++++++++ plans/quarterly/Q2-2026.md | 70 +++++++++++++++++++++++++++++++ plans/sprints/Q2-2026-S1.md | 56 +++++++++++++++++++++++++ 8 files changed, 434 insertions(+) create mode 100644 KPIs.md create mode 100644 MEMORY.md create mode 100644 plans/README.md create mode 100644 plans/daily/2026-04-13.md create mode 100644 plans/quarterly/Q2-2026.md create mode 100644 plans/sprints/Q2-2026-S1.md diff --git a/AGENTS.md b/AGENTS.md index 394bebb..ffa8c3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,3 +18,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/CLAUDE.md b/CLAUDE.md index 13e88d9..f9f0faa 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.** @@ -95,3 +133,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/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 +- ... From 351b415b4ecc3b38cdbbca7f4ea53f51bb058e65 Mon Sep 17 00:00:00 2001 From: gapview01 <107860548+gapview01@users.noreply.github.com> Date: Mon, 27 Apr 2026 09:41:25 +1000 Subject: [PATCH 4/4] chore: recover kit stash 0 --- AGENTS.md | 7 +++++++ AGENT_CHARTER.md | 6 ++++++ CLAUDE.md | 7 +++++++ REPO_CHARTER.md | 6 ++++++ 4 files changed, 26 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ffa8c3e..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`). 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 f9f0faa..dc3c15c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -125,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`). 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