diff --git a/.gitignore b/.gitignore index 552cbd9..80606dc 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md index dec5777..a792733 100644 --- a/README.md +++ b/README.md @@ -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 () 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 () 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 diff --git a/docs/PHILOSOPHY.md b/docs/PHILOSOPHY.md new file mode 100644 index 0000000..73dc31b --- /dev/null +++ b/docs/PHILOSOPHY.md @@ -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` — 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::()`, 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 +`::::::` 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 diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 31ebce0..de97de9 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -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 `/secrets/.env` — both are `.gitignore`'d.