keisei/KeiSeiKit-1.0
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: README bio-framing + PHILOSOPHY + security hardening

Browse source 
- README rewritten with bioinspired framing: KeiSeiKit as living
  neural structure of Kei (DNA / REM / Deep Sleep / creator lineage).
  All counts verified against source: 36 crates, 12 agents, 43 skills,
  12 hooks, 82 blocks.

- docs/PHILOSOPHY.md new 11.4 KB deep-dive on the substrate
  thesis, the 4-layer architecture, and roadmap (federation / signing
  / marketplace / visualization as Wave 14+).

- .gitignore hardened: .env, secrets/, *.pem, *.key, id_rsa*,
  id_ed25519*, .claude/secrets/ — public-repo safe. .env.example
  and .env.template re-included.

- docs/SECURITY.md: secret hygiene section with revoke-and-rotate
  protocol + canonical ~/.claude/secrets/.env reference (RULE 0.8).

Verified clean: defensive grep for sk-ant-, ghp_, private keys,
token/key assignments = zero hits across tree.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Parfii-bot 2026-04-23 15:44:52 +08:00
parent 700d8143ea
commit f2358397c9
4 changed files with 398 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
.gitignore vendored
View file

@ -5,3 +5,49 @@ _primitives/_rust/target/
# Agent worktrees — ephemeral orchestrator scratch dirs, never commit.
.claude/worktrees/
**/.claude/worktrees/
# Secrets
.env
.env.*
!.env.example
!.env.template
secrets/
**/secrets/
.claude/secrets/
# Keys and certs
*.pem
*.key
*.pfx
*.p12
*.jks
id_rsa
id_rsa.*
id_ed25519
id_ed25519.*
*.gpg
# Credentials / config with values
credentials.json
.netrc
.authinfo
.aws/credentials
.ssh/
# Locks (per-project policy — leave as existing if already tracked)
# Do not add: Cargo.lock (tracked per RULE 0.1 for reproducibility)
# OS + editor junk
Thumbs.db
*.swp
*.swo
.idea/
.vscode/
*.iml
# Build
node_modules/
dist/
build/
__pycache__/
*.pyc

100
README.md
View file

@ -1,8 +1,9 @@
# KeiSeiKit
**Your AI agents, structured. One manifest, eleven AI assistants. A brain that follows you across machines.**
> A living neural structure you install next to your AI assistant.
> A mini-universe where any user, from any domain, can discover a new primitive or grow a new class of agent.
Drop-in kit for Claude Code, Cursor, Continue, and Zed. Install once — get a 12-agent fleet that remembers yesterday's decisions, sleeps at night to consolidate what it learned, and lives on a USB stick you can carry between computers.
KeiSeiKit is not a toolkit. It is a substrate for cognitive growth — an opinionated neural structure of Kei that a developer installs, shapes, and extends. It sleeps when you sleep, remembers what you decided yesterday, heals mistakes it notices in itself, and runs from a directory you can put on a USB stick and carry between machines.
## Install in one line
@ -11,69 +12,104 @@ Drop-in kit for Claude Code, Cursor, Continue, and Zed. Install once — get a 1
/plugin install keisei@keisei-marketplace
```
That's it. 12 agents appear in Claude Code, 43 skills become callable as `/self-audit`, `/compose-solution`, `/schema-design`, and nightly consolidation is wired. [Other install paths →](./docs/INSTALL.md)
Twelve agents appear in Claude Code, forty-three skills become callable as `/self-audit`, `/sleep-on-it`, `/compose-solution`, `/new-project`, `/spawn-agent` — and the nightly consolidation cycle is wired. Other install paths: [docs/INSTALL.md](./docs/INSTALL.md).
## What you actually get
## The five biological principles
### 🌙 Your AI sleeps at night
KeiSeiKit is organised around five properties a living neural system has, and most software doesn't. Each principle maps to concrete code shipped in this repo.
You worked all day. At bedtime you type `/sleep-on-it what's the right database for X` and close the laptop. While you sleep, a remote agent reads your day's traces, extracts patterns, and by morning your memory-repo has a report waiting. `git pull` → read → decide. Nothing auto-injected. [How sleep works →](./docs/SLEEP-LAYER.md)
- **DNA and taxonomy.** Every agent invocation gets a 80-character deterministic identifier composed from role, capability bitmap, scope hash, task-body hash, and per-spawn nonce. Every primitive and agent is tagged along seven orthogonal facets — kingdom, mechanism, domain, layer, stage, stability, language — so the graph is queryable along any axis. See `_primitives/_rust/kei-agent-runtime/src/dna.rs` and [docs/TAXONOMY.md](./docs/TAXONOMY.md).
### 💾 One brain, any client
- **Creator lineage.** Every row in the agent ledger carries `creator_id` and `fork_parent_id`. Who spawned what, from which parent, under which DNA — traceable. No orphan artefacts, no "where did this come from". See `_primitives/_rust/kei-ledger/src/schema.rs` migration v4.
```bash
keisei mount /Volumes/MyBrain
- **Sleep. Three phases, every night.** Phase A is incubation: during the day you drop tasks into `/sleep-on-it`; at 03:00 a remote Claude agent works on them. Phase B is REM: the same agent reads the day's JSONL traces, extracts cross-session patterns, and writes a report. Phase C is NREM (every seven days by default): a conflict-scan plus refactor-engine propose a clean-up branch. Nothing auto-injects into the next session — you `git pull`, read, decide. See [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md).
- **Self-healing.** Three passive hooks (`session-end-dump`, `milestone-commit-hook`, `error-spike-detector`) feed a session retrospective. When the same mistake reappears twice, `/escalate-recurrence` offers to codify it as rule plus wiki entry plus hook — at the severity you pick. Silent-first: the first ten sessions log without prompting, so the baseline is real.
- **Growth by composition.** `/new-project` scaffolds a project across four phases with branch + ledger + artefact bundle per fork. `/spawn-agent` emits a new agent manifest. `/compose-solution` decomposes a free-text problem, greps existing atoms for prior art, and proposes the smallest artefact — agent, skill, hook, rule, block, or pipeline — that closes the gap. Every session leaves the substrate slightly larger than it found it.
The deeper theory — why these five and not others, and the analogy with hippocampal / cortical dynamics — is in [docs/PHILOSOPHY.md](./docs/PHILOSOPHY.md).
## Four layers
```
4. Portability USB stick / iCloud / S3 — keisei mount, any machine
3. Sleep Phase A (incubation) → Phase B (REM) → Phase C (NREM)
2. Cognition DNA + ledger + taxonomy + memory + self-audit
1. Substrate atoms, agents, skills, hooks, blocks, bridges
```
Your agents, memory, artifacts, and per-platform MCP binaries all live on a directory — USB stick, iCloud, S3, anything. One command mounts it into Claude Code + Cursor + Continue + Zed simultaneously. Move the drive to another computer — same state is there. [Full setup →](./docs/INSTALL.md#the-keisei-cli)
Layer 1 is the body — the reusable parts. Layer 2 is identity and memory. Layer 3 is overnight learning. Layer 4 is the ability to pick up and move.
### 🧩 Write agent rules once, ship everywhere
## What ships (verified counts)
A manifest + reusable blocks compiles into a `.md` file Claude Code reads. Edit one block — every agent using it rebuilds automatically. Same `kei-critic` behaves identically on every machine that installs the kit. [Architecture →](./docs/ARCHITECTURE.md)
- **36 Rust primitives** — pure Rust workspace crates, release-stripped, each ≤2 MB, no Python runtime. Covers the ledger, memory, router, migrate, agent runtime, forge, spawn/replay, sleep infrastructure, and the `keisei` CLI.
- **12 agents** (`kei-*` namespaced) — code-implementer, infra-implementer, ml-implementer, critic, validator, security-auditor, architect, researcher, ml-researcher, cost-guardian, modal-runner, fal-ai-runner. All carry a `substrate_role` facet.
- **43 skills** — one-command pipelines including `/new-project`, `/spawn-agent`, `/self-audit`, `/sleep-on-it`, `/sleep-setup`, `/compose-solution`, `/schema-design`, `/api-design`, `/auth-setup`, `/observability-setup`, `/ci-scaffold`, `/pr-review`, `/debug-deep`.
- **12 hooks** — pre-commit safety net, always on: assembler, validator, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, session-end-dump, milestone-commit-hook, error-spike-detector, and two capability gates.
- **82 behavioural blocks** — tested patterns composable into your own agents via `blocks = [...]` in a manifest.
- **11 capabilities / 5 roles** — the capability-graph that agents resolve at spawn time.
- **11 cross-tool bridges** — one source of truth emits `.cursorrules`, Cursor MDC, `AGENTS.md`, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit. Switch AI tools without rewriting your setup.
- **500+ tests** across the Rust workspace, green on `cargo test --workspace` on every supported OS.
### 🛡️ Catches mistakes before they commit
Every number is regenerated from source by `scripts/regen-counts.sh` — no manual drift.
Fabricated citations. Secrets in a push. Three failed retries on the same bug. All caught at the hook layer, before anything hits your repo. You don't configure it — it ships wired. [What's watched →](./docs/SECURITY.md)
## Domain-agnostic by construction
### 🌉 One source, eleven AI tools
KeiSeiKit has no hardcoded domain. The same substrate ships unchanged for biology, finance, law, medicine, music, research, game dev, ops. What's domain-aware lives in the *blocks* — reusable markdown cubes you compose into an agent manifest — and the assembler rebuilds the affected agents when a block changes. If you work in a domain the kit doesn't yet cover, the path to first-class support is a manifest plus a handful of blocks, not a fork.
Your rules get emitted to `.cursorrules`, `AGENTS.md`, `.github/copilot-instructions.md`, Cursor MDC, Windsurf, Gemini.md, Aider, Continue, Junie, Replit, and plain AGENTS.md — in one command. Switch between tools without rewriting your setup.
## How to start
## Batteries included
**Install:** the two-line plugin command above. Other paths — full profile, dev profile, MCP-only, manual, Nix, Docker — are in [docs/INSTALL.md](./docs/INSTALL.md).
- **12 agents** — `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, and more (all namespaced `kei-*` so they coexist peacefully with anything you already have)
- **43 skills** — one-command pipelines: `/new-project`, `/schema-design`, `/api-design`, `/ci-scaffold`, `/auth-setup`, `/observability-setup`, `/self-audit`, `/sleep-on-it`, ...
- **12 hooks** — pre-commit safety net, always on
- **82 behavioral blocks** — tested patterns you compose into your own agents
- **36 Rust primitives** — for the jobs where Python silently corrupts your data
**Discover a new primitive:**
```
/compose-solution "I want a hook that blocks rm -rf ~/ in any Bash call"
```
The skill greps existing atoms, proposes the smallest intervention, drafts a block if nothing matches, and hands off to `/escalate-recurrence` to persist it.
Every symbol, flag, and exit code: [docs/REFERENCE.md](./docs/REFERENCE.md)
**Grow a new agent:**
```
/spawn-agent
```
Four phases: role, task, scope, emit. The wizard writes the manifest, composes its DNA, forks a ledger row, and the assembler generates the agent markdown Claude Code will pick up.
## Under the hood (only if you care)
**Start a new project:**
```
/new-project
```
Four phases: intake, fork skeleton, parallel execution (orchestrator owns git per RULE 0.13), merge ceremony with per-branch AskUserQuestion.
Constructor Pattern: one file, one concern. TOML manifests are the source of truth. A Rust assembler compiles them to the Markdown Claude Code expects. When you edit a block, a PostToolUse hook rebuilds every affected agent. Rust is the backbone because the type system catches the class of mistakes LLMs most often introduce — `None` vs `[]`, missing `.await`, unhandled `Result` — at compile time, so they can't ship. Python is reserved for places where Python is genuinely better.
## Portability
Full build pipeline, cross-tool bridge mechanics, meta-composer, sleep-layer internals → [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
Every primitive is a pure Rust binary ≤2 MB. Every hook is POSIX shell. Every skill is markdown. Every manifest is TOML. The `keisei` CLI mounts a brain-directory into Claude Code + Cursor + Continue + Zed simultaneously; the directory can live on a USB stick, iCloud, S3, or any filesystem. Move it to another machine and the same agents, the same memory, the same artefact bundles are there. [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md).
## Under the hood
Constructor Pattern: one file, one concern. TOML manifests are the source of truth. A Rust assembler compiles them to the Markdown Claude Code expects. When a block changes, a PostToolUse hook rebuilds every affected agent. Rust is the backbone because the type system catches the class of mistakes LLMs most often introduce — `None` vs `[]`, missing `.await`, unhandled `Result` — at compile time, so they cannot ship. Python is reserved for the places where Python is genuinely better.
Build pipeline, cross-tool bridge mechanics, meta-composer internals, sleep-layer details → [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
## Docs
| | |
|---|---|
| [PHILOSOPHY.md](./docs/PHILOSOPHY.md) | The biological principles, in depth |
| [INSTALL.md](./docs/INSTALL.md) | All install paths, profiles, `keisei` CLI, hook controls |
| [REFERENCE.md](./docs/REFERENCE.md) | Every primitive, hook, skill with flags and exit codes |
| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, bridges, meta-composer |
| [SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Nightly cycle + self-audit |
| [REFERENCE.md](./docs/REFERENCE.md) | Every primitive, hook, skill with flags and exit codes |
| [SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Phase A / B / C nightly cycle + self-audit |
| [TAXONOMY.md](./docs/TAXONOMY.md) | The seven-facet vocabulary |
| [SUBSTRATE-SCHEMA.md](./docs/SUBSTRATE-SCHEMA.md) | Atom contract |
| [SECURITY.md](./docs/SECURITY.md) | Threat model + mitigations |
| [USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) | Portable brain — macOS / Linux / Windows |
| [WHY.md](./docs/WHY.md) | The full story of why this exists |
| [CHANGELOG.md](./CHANGELOG.md) | What changed, version by version |
| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format details |
## About
## Authorship
Built by Denis Parfionovich (<parfionovich@keilab.io>) while running 4–8 parallel Claude Code terminals every day. What you're looking at is the scaffolding that makes that possible — shared now so you don't have to build your own.
Forks and PRs welcome. Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution.
Built by Denis Parfionovich (<parfionovich@keilab.io>) at KeiLab, while running 4–8 parallel Claude Code terminals every day. What you are looking at is the scaffolding that makes that possible — shared now so you don't have to build your own. Forks and pull requests welcome.
## License

266
docs/PHILOSOPHY.md Normal file
View file

@ -0,0 +1,266 @@
# Philosophy — KeiSeiKit as a Living Neural Structure
> The README claims KeiSeiKit is "a living neural structure." This document
> is the long form of that claim: which biological properties we chose,
> why, how each one maps to code shipped in this repo, and what the
> tradeoffs are.
---
## The one-line thesis
A software toolkit accumulates features. A living neural structure
accumulates identity, memory, lineage, and the ability to recover from its
own mistakes. KeiSeiKit is built around the second list.
## The five properties
A neural system is distinguishable from a collection of functions by five
properties. Each one is load-bearing — remove it and the structure stops
being alive in the relevant sense.
1. **Identity** — each unit has a stable, reproducible name, not a random
UUID or a human-friendly slug that drifts.
2. **Lineage** — each unit knows who produced it and from what.
3. **Memory** — the system remembers what it did yesterday, across
restarts, across machines, across sessions.
4. **Consolidation** — memory is not raw logs; it is periodically replayed
and compressed into patterns.
5. **Corrective learning** — mistakes the system notices in itself
surface as explicit artefacts (rules, hooks, tests) the next session
inherits.
The rest of this document maps each property to the shipped code.
---
## 1. Identity — DNA
Every agent invocation resolves to a deterministic 80-character string:
```
<role>::<caps-bitmap>::<scope-hash>::<body-hash>-<nonce>
```
- `role` — role slug (e.g. `edit-local`, `research-web`).
- `caps-bitmap` — the resolved capability list, encoded as ordered 2-char
atom codes (`NG` = no-git-ops, `FW` = files-whitelist, `TG` = tests-green).
- `scope-hash` — 8 hex chars (32-bit) of SHA-256 over canonicalised scope.
- `body-hash` — 8 hex chars of SHA-256 over the task body text.
- `nonce` — 8 hex chars of `rand::random::<u32>()`, full 32-bit entropy.
The shape is enforced by `kei-agent-runtime::dna::parse`. Two invocations
with the same role, capability set, scope, and task body produce the same
`<role>::<caps>::<scope>::<body>` prefix, and differ only by nonce. That
makes DNA both deterministic (for reasoning) and unique (for collision
resistance — birthday threshold ≈ 65k agents per role+caps group).
**Why not UUIDs.** A UUID hides what the agent was supposed to do. A DNA
string is greppable: you can look at a ledger row and see the capability
bitmap without joining five tables.
**Why not slugs.** Slugs collide and drift. DNA is stable under renames
because the role slug is part of the hash input, not a sidecar.
Source: [`_primitives/_rust/kei-agent-runtime/src/dna.rs`](../_primitives/_rust/kei-agent-runtime/src/dna.rs).
## 2. Lineage — creator_id and fork_parent_id
Every row in the agent ledger carries two additional columns:
- `creator_id` — DNA or human id of whoever spawned this row.
- `fork_parent_id` — DNA of the agent this row was forked from, if any.
This is SQL-level lineage. Any artefact produced during a session can be
traced back to the agent that produced it, to the agent that spawned
*that* agent, to the human session the chain started from.
**Why this matters.** Software without lineage produces "where did this
file come from" questions at merge time. Lineage makes them disappear:
the merge-ceremony skill prints the DAG and the human picks which forks
merge, which squash, which defer.
Schema: [`_primitives/_rust/kei-ledger/src/schema.rs`](../_primitives/_rust/kei-ledger/src/schema.rs) migration v4.
## 3. Memory — three layers
The memory layer is deliberately three-tiered, mirroring the hippocampal
+ cortical split:
1. **Raw episodes** — session JSONL traces, append-only, one file per
session. This is the hippocampus: fast, stateful, volatile (survives
until the next full pull), not interpreted.
2. **Project memory** — `memory/{project}.md` one file per project,
self-contained, constraints + stack + status + learnings with
evidence grades.
3. **Index** — `MEMORY.md`, one line per project, ≤200 lines total. No
inline data. Reading this file gives the shape of the world.
Any session's "what did we decide last time" is a read of the
corresponding project file, not a scroll through chat history. The index
guarantees that read is fast.
**Why this layering.** A single giant memory file stops being read
because it cannot be scanned. A million tiny files stop being read
because there is no entry point. Three layers — index → project file →
raw traces — give you O(1) navigation to the right detail.
Source: `~/.claude/rules/memory-protocol.md` (the full memory-protocol
rule, shared across every KeiLab project).
## 4. Consolidation — REM and NREM
Raw traces become patterns only if something replays them. KeiSeiKit's
sleep layer runs in three phases on a nightly schedule:
### Phase A — Incubation ("sleep on it")
During the day, you drop tasks into `/sleep-on-it`. Each task gets a
priority (quick 15 min / standard 60 min / deep 240 min / marathon
480 min) and optionally a checkpoint cadence. At 03:00 local a remote
Claude Code agent on Anthropic's cloud picks up the queue (up to 480
minutes total across ≤ 5 tasks, packed greedily in FIFO order) and
works until the budget or checkpoint fires.
Biological analog: the overnight consolidation of un-finished intentions
(Wagner et al. 2004, *Nature*). Things unsolved when you fell asleep are
often solved by morning not because the brain ran harder, but because
it ran offline.
### Phase B — REM consolidation
After Phase A, the same agent reads the last 24 h of JSONL traces, diffs
them against the previous report, and writes
`reports/sleep-YYYY-MM-DD.md`. Cross-session patterns (≥ 3 occurrences
across ≥ 2 distinct sessions) are prepended to `backlog.md`.
Biological analog: REM dream-state. Pattern extraction, not raw replay.
### Phase C — NREM deep sleep
Every seven days (by default; configurable to zero to disable) the
pipeline also runs `kei-conflict-scan` → `kei-refactor-engine` → optional
`kei-graph-check`. The output is a **plan-only** markdown file or a
**plan + fork** branch (`deep-sleep/YYYY-MM-DD`) with `git apply`-ready
changes. Ambiguous conflicts are excluded from any auto-patch and listed
explicitly for human decision.
Biological analog: NREM slow-wave sleep. System-level consolidation.
Integrating, not just reviewing.
### The no-feedback-loop invariant
Nothing the cloud agent writes is ever auto-injected into a Claude Code
session. The morning report is for human review. Any rule or hook that
emerges from it is installed by hand via `/escalate-recurrence`. This
is a deliberate architectural choice: auto-learning loops without human
signoff are how models drift.
Source: [`docs/SLEEP-LAYER.md`](./SLEEP-LAYER.md) and `~/.claude/rules/sleep-layer.md`.
## 5. Corrective learning — self-audit
Three passive hooks run during any session:
- `session-end-dump` — on Stop, archives the session trace and ingests
it into `kei-memory`.
- `milestone-commit-hook` — on `feat:` / `refactor:` / merge commits,
appends a one-line summary to `audit-backlog.md`.
- `error-spike-detector` — when three or more errors occur in the last
twenty tool calls, tags the pattern.
These feed the `/self-audit` skill, which classifies recurring problems
and surfaces them via click-only `AskUserQuestion`. The user can
route a finding to:
- `/escalate-recurrence` — codify as rule + wiki + optional hook.
- `/debug-deep` — 5-phase root-cause analysis.
- hook-only — mechanical block / enforce / warn / remind.
- backlog — log, surface next session.
- postpone — keep open, resurface later.
**Silent-first mode.** The first ten sessions log only — no prompts.
This prevents false-positive fatigue while the memory store is still
empty. Session 11 onward, the self-audit starts surfacing items.
Source: `~/.claude/rules/session-self-audit.md` (RULE 0.14) and
`skills/self-audit/`.
---
## Growth — the sixth property, emergent
A substrate that satisfies properties 1–5 can support a sixth that is
harder to design for directly: **growth**. New primitives, new blocks,
new agents, new projects enter through user-driven commands and
accumulate in a way the next session can find.
- **New primitive.** `/compose-solution` decomposes a free-text problem,
greps existing atoms for prior art, and drafts a block if nothing
matches. The draft is persisted on user click, discoverable thereafter.
- **New agent.** `/spawn-agent` emits a manifest + DNA + ledger row. The
assembler hook rebuilds the markdown Claude Code picks up.
- **New project.** `/new-project` is a 4-phase skill: intake, fork
skeleton, parallel execution (orchestrator owns git per RULE 0.13),
merge ceremony.
Growth is not a feature we implemented. It is what the other five
properties produce when you compose them.
---
## What this is not
A neural network. The name "neural structure" is an analogy about
properties (identity, lineage, memory, consolidation, corrective
learning), not a claim about weights or gradients. Nothing in KeiSeiKit
trains on your data. The cloud agent in the sleep layer is a standard
Claude Code session with scheduled triggers — it reads your traces to
write a report, not to fine-tune itself.
A federation. As of v0.24, KeiSeiKit ships as a single-user substrate
installed next to Claude Code. Cross-user signing, marketplace publishing
of blocks, and federation are on the roadmap but not yet shipped. If a
doc claims otherwise, that doc is stale.
A framework. A framework tells you how to structure your application. A
substrate gives your agents identity, lineage, memory, and sleep —
nothing about it dictates the application. You can delete every skill
in this repo and the substrate still works; you can also add fifty more
and it still works.
---
## The constraints that shaped this
Three constraints, made explicit because they push back against common
defaults:
- **Constructor Pattern.** One file, one class, one concern. Files
greater than 200 lines are decomposed. Functions greater than 30
lines are split. No mixins, no DI containers, no abstract factories.
This keeps the graph readable by both humans and Claude.
- **Rust-first default.** New primitive code is Rust unless there is a
cited exception (ML training > 10M params / existing-language project
/ platform UI / browser-DOM / one-off < 50 lines / external binding
only / explicit user override). The reason is not performance — it is
that the Rust type system catches the class of mistakes LLMs most
often introduce (`None` vs `[]`, missing `.await`, unhandled
`Result`) at compile time.
- **Local-first.** Nothing is pushed to GitHub by default. The sleep
layer's memory-repo is user-owned, private, on whatever remote the
user chose. This is a hard rule (RULE 0.1) because the portfolio
contains unfiled patent IP.
If these constraints feel restrictive, they are — deliberately. They
are the shape of the substrate, not decorations.
---
## Further reading
- [ARCHITECTURE.md](./ARCHITECTURE.md) — build pipeline + bridges + meta-composer
- [SLEEP-LAYER.md](./SLEEP-LAYER.md) — Phase A / B / C in depth
- [TAXONOMY.md](./TAXONOMY.md) — the seven-facet vocabulary
- [SUBSTRATE-SCHEMA.md](./SUBSTRATE-SCHEMA.md) — atom contract
- [WHY.md](./WHY.md) — the full origin story

18
docs/SECURITY.md
View file

@ -118,3 +118,21 @@ For the underlying discipline: these mitigations are driven by rules in the user
- **RULE 0.13** — ORCHESTRATOR BRANCH FIRST (agents write files; orchestrator owns git)
- **RULE 0.14** — SESSION SELF-AUDIT
- **RULE 0.15** — SLEEP LAYER (three-phase nightly consolidation)
## Secret hygiene
This repository is public. The `.gitignore` actively blocks commits of:
- `.env` / `.env.*` (except `.env.example`, `.env.template`)
- `secrets/`, `**/secrets/`
- Key files: `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*`
If you accidentally stage a secret:
1. **Do not push.** Drop it from the working tree immediately.
2. **Revoke** the leaked credential at its provider dashboard.
3. **Rotate** any adjacent credentials that may share the leak context.
4. If already pushed to remote: rewrite history (`git filter-repo`) and force-push is NOT safe on a widely-cloned repo; prefer revoke + rotate + new-commit-atop.
The canonical secret store for Claude Code is `~/.claude/secrets/.env`
(chmod 600, RULE 0.8 in your personal umbrella). Project-specific
tokens live at `<repo>/secrets/<name>.env` — both are `.gitignore`'d.