docs(readme): restore About section + nightly-cycle overview + security model
Adds 6 missing pieces flagged by readme review:
1. ## About — author attribution + "not a product" positioning + "Why
Rust, not Python" (was removed in 1f3aaca, but load-bearing context
for new users). Keeps the product-oriented greeting intact above it.
2. ## Install — plugin vs classic two-path table up front; links to
PLUGIN.md (v0.16+ Anthropic plugin format was previously un-linked).
3. ## The nightly cycle at a glance — unified ASCII overview of the
three-phase sleep cycle (A incubation → B REM → C NREM), biological
analog, phase-interaction rules (marathon owns night, Phase C cadence,
morning report is human-only).
4. ### Deep-sleep NREM consolidation — 4-primitive pipeline diagram
(conflict-scan → refactor-engine → graph-check via kei-store) plus a
concrete example of a detected conflict.
5. ## Security model — 7 bullets covering memory-repo privacy, RULE 0.1,
secrets-guard, GitHub Actions SHA pinning, S3 SSRF guard, marker
0o600, exFAT/FAT32 warning. Plus battle-matrix mention.
6. ## Docs — link index to CHANGELOG / PLUGIN / USB-BRAIN guide / battle
tests (none of those four files were referenced from README before).
README.md: +83 lines (1221 → 1304).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Parfii-bot
parent
5ec90ca241
commit
b55c3d6ef3
1 changed files with 83 additions and 0 deletions
83
README.md
83
README.md
|
|
@ -12,6 +12,16 @@ KeiSeiKit is that structure: persistent agent memory across sessions, pre-commit
|
|||
|
||||
**Rust-first by design.** Every primitive that can be Rust, is Rust. Type-system guarantees remove entire classes of hallucination at compile time: no `None`-vs-`[]` confusions, no missing `.await`, no unhandled `Result`. For LLM-authored code this is not a style preference but a survival constraint.
|
||||
|
||||
## About
|
||||
|
||||
Built by Denis Parfionovich (<parfionovich@keilab.io>) as a personal working environment — not a commercial product. The problems it solves are ones I hit every day across 4–8 parallel Claude Code terminals: forgetting between sessions, repeating the same mistake on the third try, parallel agents clobbering each other's files, a hallucinated API name shipped to production. None of these are solvable by a better prompt. They are solvable by structure around the prompt.
|
||||
|
||||
**Why Rust, not Python.** Transformers write Python confidently and wrongly. Five minutes to a plausible-looking function, two hours to debug why `dict.get("key", None) or []` silently swallowed an empty list, or why an async context manager leaked a file handle across a retry loop. Rust's type system catches whole categories of those errors at compile time — the model literally cannot ship a `None`-vs-`[]` confusion, a missing `.await`, or an unhandled `Result`, because the compiler refuses. For an LLM-written codebase this is not aesthetic preference, it is survival. Every Rust primitive here is one category of hallucination the transformer is no longer allowed to commit.
|
||||
|
||||
Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, constructor-pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and the three-phase sleep layer (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly incubation + REM + NREM consolidation).
|
||||
|
||||
Treat this as **my sample, not a claim of originality.** I work from my own rules stacked in one place and cannot always tell what came from somewhere I have read and what came from my own head. Forks and PRs welcome from everyone, not only from those who write code. If you hit a problem with Claude Code and have an idea for solving it, open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues) — a well-formulated problem is already half the solution.
|
||||
|
||||
---
|
||||
|
||||
## At a glance
|
||||
|
|
@ -69,6 +79,13 @@ The kit is MIT-licensed and fully generic — install it on a fresh machine and
|
|||
|
||||
## Install
|
||||
|
||||
Two install paths — pick whichever fits your Claude Code version:
|
||||
|
||||
| Path | Command | Best for |
|
||||
|---|---|---|
|
||||
| **Plugin** (v0.16+, recommended on Claude Code 2.1+) | `/plugin marketplace add KeiSei84/KeiSeiKit` then `/plugin install keisei@keisei-marketplace` | Agents + skills + hooks + MCP. Zero cargo build. See [PLUGIN.md](./PLUGIN.md). |
|
||||
| **Classic** `./install.sh` | Below | Full kit incl. 25 Rust primitives + 13 shell primitives. Required for the `ops` / `dev` / `full` profiles. |
|
||||
|
||||
```bash
|
||||
git clone <your-fork-of-this-repo> KeiSeiKit
|
||||
cd KeiSeiKit
|
||||
|
|
@ -986,6 +1003,35 @@ Manual trigger: `/self-audit` skill (same flow, invoked on demand).
|
|||
|
||||
Requires the `kei-memory` primitive. Included in the `dev` and `full` profiles; otherwise add via `./install.sh --add=kei-memory`.
|
||||
|
||||
## The nightly cycle at a glance
|
||||
|
||||
The sleep layer is a **three-phase nightly cycle** on an Anthropic-cloud agent. The three phases run in order on the same scheduled trigger; each is covered in its own section below.
|
||||
|
||||
```
|
||||
YOUR NIGHT
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
Day →→→ │ Phase A Phase B Phase C │ →→→ Morning
|
||||
│ INCUBATION REM NREM │
|
||||
│ "sleep on it" consolidation deep-sleep │
|
||||
│ v0.12.0 v0.11.0 v0.13.0 │
|
||||
│ (queued tasks) (trace patterns) (conflict │
|
||||
│ refactor) │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
↓ ↓ ↓
|
||||
sleep-results/ reports/sleep-*.md sleep-deep/*.md
|
||||
<uuid>.md (always) (every N days)
|
||||
```
|
||||
|
||||
**Biological analog.** Your Mac is the hippocampus (fast, stateful, volatile — captures raw episodes). The memory-repo is the transport layer. The cloud agent is the neocortex (slow, stateless, generalising). The morning `git pull` is the recall. Phase A mirrors the "sleep on it" effect (Wagner et al. 2004, *Nature*), Phase B mirrors REM dream-state pattern extraction, Phase C mirrors NREM slow-wave system consolidation.
|
||||
|
||||
**Phase interaction rules (important):**
|
||||
|
||||
- A `marathon` task in Phase A (8-hour budget, 1 task only) **owns the whole night** — Phases B and C are skipped for that night. Traces are append-only, so the next night's Phase B picks up the skipped backlog.
|
||||
- Phase C only fires when today is a multiple of `DEEP_SLEEP_CRON_DAYS` (default 7) counted from your install date. Anchor lives in `sync-repo/reports/install-anchor.txt`.
|
||||
- The morning report is for **HUMAN review**. It is NEVER auto-injected into a Claude Code session. Any rule or hook that emerges from it is installed via `/escalate-recurrence` — not by the cloud agent.
|
||||
|
||||
Governed end-to-end by RULE 0.15 in `~/.claude/rules/sleep-layer.md`.
|
||||
|
||||
## Cloud REM sync (sleep layer, v0.11.0)
|
||||
|
||||
Run a nightly "sleep" cycle on Anthropic's cloud — no laptop, no infra, no DevOps.
|
||||
|
|
@ -1036,6 +1082,22 @@ Results in `sync-repo/sleep-results/<uuid>.md`, linked from the next morning's R
|
|||
|
||||
A third nightly phase — **Phase C** — runs after REM on a user-chosen cadence (default: every 7 days). Biological analog: NREM slow-wave-sleep system consolidation. The remote agent scans your memory-repo for conflicts across rules, hooks, `_blocks/`, and memory (contradictory directives, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations) and produces a structured refactor plan.
|
||||
|
||||
**4-primitive pipeline, in order:**
|
||||
|
||||
```
|
||||
kei-conflict-scan → kei-refactor-engine → kei-graph-check (via kei-store transport)
|
||||
(detect) (propose) (verify) (read/write memory-repo)
|
||||
```
|
||||
|
||||
1. `kei-conflict-scan` reads `_rules/`, `hooks/hooks.json`, `_blocks/`, and `memory/` and emits a typed conflict list (name-collision, matcher-overlap, duplicate-block, orphan-wikilink, CP-violation).
|
||||
2. `kei-refactor-engine` groups conflicts by safe-to-auto-resolve vs `requires_human_decision` and writes the plan + auto-resolve markdown.
|
||||
3. `kei-graph-check` walks every wikilink / block-ref / handoff-ref in the proposed state; if anything fails to resolve, the fork branch is blocked and the plan is annotated.
|
||||
4. `kei-store` is the transport — reads the pre-state from your GitHub / Forgejo / Gitea / FS / S3 backend and writes the two output files back atomically.
|
||||
|
||||
**Concrete example** (real category, paraphrased):
|
||||
|
||||
> Conflict detected: hook `no-github-push.sh` (PreToolUse:Bash, matcher `git push`) and rule file `patents.md` (§"Never reference unfiled applications") both govern the same risk surface — a github push containing unfiled-patent language. The hook blocks on URL; the rule blocks on content. Suggested refactor: keep both (they are complementary), but add a cross-ref from `patents.md` to the hook so a future reader sees the two-layer defence. Auto-resolvable (pure documentation edit, no behaviour change). Written to `YYYY-MM-DD-autoresolve.md` for human review.
|
||||
|
||||
Two output modes, chosen once in `/sleep-setup` Phase 3b:
|
||||
|
||||
- **Plan only** (default) — markdown report in `sync-repo/sleep-deep/YYYY-MM-DD-plan.md`. Read in the morning, decide what to merge by hand.
|
||||
|
|
@ -1216,6 +1278,27 @@ Phase 6 is the feedback loop: when a component has no prior art, the skill draft
|
|||
|
||||
See `skills/compose-solution/SKILL.md` and its phase files (`phase-1-intake.md` through `phase-7-assemble.md`) for the full 7-phase pipeline.
|
||||
|
||||
## Security model
|
||||
|
||||
What the kit touches, what it never touches, and the mitigations baked in:
|
||||
|
||||
- **Memory-repo must be private.** Sleep-sync pushes your session traces (prompts, tool calls, file paths, code snippets) to a git repo you control. `/sleep-setup` Phase 1 warns loudly on PUBLIC visibility. A public memory-repo leaks everything your agents have seen. If the session is marked `[PATENT-IP]` or runs in a banned-project CWD, `session-end-dump.sh` skips the push entirely — local trace is kept, never leaves the machine.
|
||||
- **No GitHub push for kit-internal state.** RULE 0.1 forbids `git push` to github.com for any repo containing unfiled-patent IP. Kit ships `genesis-leak-guard.sh` as a pre-commit hook symlink template to keep patent-sensitive terms off any remote.
|
||||
- **Secrets by reference only.** `secrets-guard` hook (Rust) blocks hardcoded tokens at `PreToolUse(Edit|Write)`. Every SSH key, API key, deploy token lives in `~/.claude/secrets/.env` (chmod 600, gitignored) or per-project `secrets/*.env`. Hook detects OpenAI/Anthropic/GitHub/Slack/AWS/Telegram token shapes plus PEM private keys (see RULE 0.8).
|
||||
- **Supply-chain defences.** All GitHub Actions in `.github/workflows/` are pinned by full commit SHA (defends against CVE-2025-30066-class mutable-tag attacks). `scripts/validate-workflow-shas.sh` verifies every pin; `scripts/install-actionlint.sh` checks SHA-256 of the downloaded tarball before extraction. Dependabot raises weekly PRs for SHA updates.
|
||||
- **S3 / R2 / MinIO hardening.** `kei-store::s3_cloud::validate_endpoint` rejects loopback, link-local, and cloud-metadata hosts (`127.0.0.0/8`, `169.254.0.0/16`, `metadata.google.internal`, …) by default to close the SSRF / IMDS-credential-leak surface. Plain HTTP requires opt-in. Non-AWS endpoints must set explicit `access_key_env` + `secret_key_env` — the AWS default credential chain is not consulted.
|
||||
- **Brain attach-marker is owner-only.** `~/.keisei/attached.toml` is `chmod 0o600` on unix. Every manifest-sourced string printed by `keisei status` / `attach` / `mount` / `detach` is scrubbed through a control-byte sanitiser — closes the escape-sequence-injection surface from a malicious `brain.name`.
|
||||
- **exFAT / FAT32 warning.** SQLite WAL shared-memory mmap is unreliable on those filesystems; `keisei mount` will corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Brain load prints an advisory. See `docs/USB-BRAIN-GUIDE*.md` for APFS / ext4 / NTFS-native walkthroughs.
|
||||
|
||||
Install-test battle matrix runs every profile against Ubuntu 24.04 + Alpine 3.19 + Debian 12 (`tests/battle/`) — "does it work on a fresh machine?" signal before each release.
|
||||
|
||||
## Docs
|
||||
|
||||
- [CHANGELOG.md](./CHANGELOG.md) — full release notes, generated from Conventional Commits by `kei-changelog`
|
||||
- [PLUGIN.md](./PLUGIN.md) — Anthropic plugin-format install path (v0.16+) and differences from classic installer
|
||||
- [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) — portable brain on removable media; platform splits for macOS / Linux / Windows
|
||||
- [tests/battle/README.md](./tests/battle/README.md) — Docker install-test matrix
|
||||
|
||||
## License
|
||||
|
||||
MIT. See `LICENSE` in this directory.
|
||||
|
|
|
|||
Loading…
Reference in a new issue