PreToolUse hooks route through kei-capability check when orchestrator
registers a capability via KEI_CAPABILITY_NAME env var on agent spawn.
hooks/agent-capability-check.sh (22 LOC):
- Pass-through (exit 0) when KEI_CAPABILITY_NAME unset — no-op by default
- Fail-open (exit 0) when kei-capability binary missing — kit convention
- Sources _lib/gate.sh for KEI_DISABLED_HOOKS / KEI_HOOK_PROFILE respect
- exec kei-capability check "$CAP_NAME" when active
hooks/agent-capability-verify.sh (24 LOC):
- Orchestrator-driven, NOT a Claude Code native hook
- Carries env: AGENT_ID, TASK_TOML, WORKTREE_PATH, MAIN_REPO, RUN_MODE
- exec kei-capability verify "$CAP_NAME"
Registered in hooks/hooks.json + settings-snippet.json under both
PreToolUse:Bash and PreToolUse:Edit|Write matchers. Internal NotApplicable
returns exit 0 so non-matching tool calls cost nothing.
install.sh unchanged — hooks/*.sh glob picks up both new files.
tests/hook_wiring_integration.sh (64 LOC) — 3 contract assertions:
(1) pass-through on unset KEI_CAPABILITY_NAME
(2) deny+exit 2 on git-op pattern
(3) allow+exit 0 on cargo-check pattern
Multi-capability routing (for phase 5): KEI_CAPABILITY_NAME currently
holds ONE name. When a role requires N capabilities, orchestrator will
either iterate or kei-capability gains a compose subcommand. Design
note left for phase 5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Refocuses README from defensive ("here's what LLMs do wrong, here's how we fence it")
to welcoming ("here's what you get, install is one line, complexity lives under the
hood"). Same factual content, same feature count, reorganized for new visitors.
Key changes:
- Hero opens with user outcome, not LLM failure modes
- Install moved to 2nd block (was buried mid-README)
- Features rewritten as scenarios ("Your AI sleeps at night") not specs
- "Batteries included" frames counts as confidence signal, not overwhelm
- "Under the hood (only if you care)" explicitly optional section for devs
- "About" confident — 4-8 parallel terminals flex, not self-deprecation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sibling SSoT to SUBSTRATE-SCHEMA.md (atom substrate). This one decomposes
agent invocations rather than code primitives.
Core contribution — the capability TRIPLET, not just text:
- text.md — what agent reads (prompt fragment)
- gate.sh — PreToolUse hook (runtime enforcement)
- verify.sh — on-return predicate run from main repo (not worktree)
Motivation from substrate v1 orchestration audit:
- 40% prompt boilerplate across 7 spawns (git-ban + constructor-pattern +
report format etc. copy-pasted each time)
- Self-reported green tests broke at integration (E1 jsonschema
regression — agent claimed PASS from worktree but main workspace
failed; caught only by integration test)
- Scope violations (E1 touched invoke.rs when E3 was supposed to own it;
surfaced only at merge)
Triplet closes all three gaps: capabilities aren't promises agents make
in prose, they're enforced by gate hooks pre-exec and verified by
predicates on return from main branch clean state.
Schema specifies:
- Capability atom layout: _capabilities/<category>/<slug>/
- capability.toml frontmatter shape
- text.md / gate.sh / verify.sh contracts
- Role = bundle of capabilities (5 roles: read-only, explorer, edit-local,
edit-shared, git-ops)
- task.toml shape (orchestrator-written per spawn; parameterizes roles)
- kei-agent-runtime crate contract: compose + spawn + verify + run
- Initial 10-capability inventory for phase 1
- 6-question decision log with defaults
- 5-phase parallel build plan (phases 1-4 parallel, ~5-7 days wall time)
Open questions flagged at bottom for review before AGENT-SCHEMA-LOCKED.md.
Once locked: sibling SSoTs (atoms + agents) evolve symmetrically — agents
compose atoms, atoms compose agents (ultimate goal).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Remove std::process::Command invocation of scripts/new-atom.sh from
kei-forge. Templating moves to pure Rust — eliminates the
sed-metacharacter injection class structurally, on top of the
description whitelist that E2 added as defence-in-depth.
src/generate.rs split into 4 Cubes (Constructor Pattern):
- generate/placeholders.rs — 6-token substitution, longer-first ordering
- generate/paths.rs — TargetPaths::resolve + assert_none_exist
- generate/rollback.rs — Drop-based atomic rollback (Rust idiom for
shell `trap ERR`)
- generate/atom_tests.rs — 5 tempdir integration tests
generate.rs dropped from 295 → 159 LOC as orchestration thin wrapper.
Behavioural parity with scripts/new-atom.sh maintained: same 6 tokens,
same order, refuse-overwrite, atomic rollback, same file-list
ordering. scripts/new-atom.sh untouched on disk (still usable as
standalone CLI).
Cargo.toml: removed mock-generate feature flag (no longer needed —
pure-Rust tests use tempfile::TempDir), added tempfile dev-dep.
Tests: 44/44 (was 29 with mock-generate; +15 new pure-Rust unit tests
across placeholders/paths/rollback/atom_tests).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three post-E1/E2/E3-merge items:
1. Schema amendment A-1 (architect P0-a, non-breaking clarification):
input.schema and output.schema are REQUIRED for all atom kinds. The
shared kei-atom-discovery parses them as Option<PathBuf> only to allow
tolerant skip-on-missing (stderr warn), not to permit absent schemas.
Resolves Stream C / Stream D enforcement asymmetry documented in
critic finding #6.
2. Cross-stream integration test (architect P0-b): tests/substrate_integration.sh
builds release binaries, scaffolds a test atom corpus, runs
schema-lint + list-atoms + atoms-discover + invoke; asserts all four
streams agree on the same atom corpus and exit codes honour the
locked §Runtime contract. Previously missing — only manual smoke
checks existed.
3. Fix regression introduced by E1's jsonschema 0.18 upgrade:
"relative URL without a base" on compile when schema declared a
relative $id like "kei-task/atoms/schemas/create-input.json".
validate.rs now synthesises an absolute file:// $id from the
canonicalised schema path before compile. Internal $refs still
resolve relative to the schema file; LocalFileResolver still confines
to the schema's parent dir. Integration test catches this.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three HIGH security findings resolved in _primitives/_rust/kei-forge/:
- F-1: DNS rebinding — require_local_host middleware returns 421 on
non-localhost Host headers
- F-2: CSRF via urlencoded — require_json_content_type middleware
returns 415 on non-JSON; form HTML now POSTs JSON via fetch()
- crit#1/SA F-7: description sed injection — whitelist validator rejects
newline/CR/tab/NUL/backtick/$/length>200, blocks the shell-script attack
at the Rust layer
- crit#11: missing security headers — CSP, X-Frame-Options DENY,
X-Content-Type-Options nosniff, Referrer-Policy no-referrer on GET /
Zero new deps (axum 0.7 middleware::from_fn + HeaderMap native).
Constructor Pattern compliant — 6 Cube files, largest 231 LOC including tests.
Tests: 29/29 (was 12/12; +17 new). Includes 4 adversarial integration
tests for each defence layer.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pilot refactor per locked substrate schema. kei-task migrated to atom
layout:
- atoms/<verb>.md — YAML frontmatter + human body for 3 verbs
- atoms/schemas/<verb>-{input,output}.json — JSON Schema draft-07
- src/atoms/<verb>.rs — typed Input/Output/Error + pub fn run()
- src/atoms/mod.rs — module registry
- Cargo.toml [package.metadata.keisei] — crate-level substrate data
- src/main.rs — dispatcher for 3 pilot commands via atoms::
Zero behaviour change: 7/7 integration tests pass before and after
(create_and_get, update_persists, cycle_detected, milestone_linking,
dependency_chain_traversal, task_graph_edges, search_finds_task).
main.rs still has 5 non-migrated subcommands (update, graph,
dependency-chain, milestone, link-milestone) — scope discipline, they
migrate in later passes. main.rs 120 → 132 LOC.
Stream B pilot reference — other crates follow this pattern in v0.24+.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New crate _primitives/_rust/kei-forge/ exposing POST /forge over axum
on 127.0.0.1:8747. Shell-outs to scripts/new-atom.sh for generation.
5-input inline HTML form, no JS required. 9 unit + 3 integration tests
green via `cargo test --features mock-generate`.
Registered kei-forge in workspace members.
Stream A of substrate v1 parallel build — see docs/SUBSTRATE-SCHEMA.md.
Spec pre-locked; schema immutable until 2026-06-03 or revocation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Schema at SUBSTRATE-SCHEMA.md (revised 2026-04-22) is immutable until
~2026-06-03 or explicit user revocation. 4 parallel streams may now
proceed independently against this contract.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Schema revisions per user review 2026-04-22 (all 6 open questions resolved
— see §Decision log in SUBSTRATE-SCHEMA.md):
- #3 side_effects: string tags → structured { op, domain } objects (user:
"лучше сразу с запасом")
- #4 capabilities.toml: DROPPED entirely (user: "почему не мд?"). SSoT is
atoms/*.md. Crate-level metadata moves to Cargo.toml
[package.metadata.keisei] — Cargo-native, no drift, no build.rs, no
generated files to commit. kei-sage + kei-runtime walk atoms/*.md
directly.
- #5 atom template: shipped in this PR (user: "ui же параллельно! создавай
все!") so Streams B/C/D can scaffold atoms from day 0 without waiting
for Stream A (kei-forge UI).
- #1/#2/#6 confirmed as drafted (draft-07, `::` separator, per-atom errors).
New files:
- _templates/atom/ — 5-file template set with placeholder substitution
(__CRATE__, __VERB__, __KIND__, __DESCRIPTION__ etc). Covers
atoms/<verb>.md, schemas/<verb>-{input,output}.json, src/atoms/<verb>.rs,
tests/<verb>_smoke.rs. Each file is a minimal working skeleton.
- scripts/new-atom.sh — POSIX bash generator (bash for $'\n' / readonly /
trap). Validates verb is lowercase kebab-case, kind is one of
command|query|stream|transform. Refuses to overwrite existing files.
Rolls back on any failure (trap ERR deletes all generated files so no
half-scaffolded state). Tested: produces 5 files, placeholder
substitution correct on smoke-test crate.
Stream B (atoms refactor) updated to drop the "generates capabilities.toml
via build.rs" wording — now just "writes atoms/*.md + updates Cargo.toml
[package.metadata.keisei]". Stream D reads atoms/*.md + Cargo.toml, not
capabilities.toml.
Schema status: revisions applied, decision log complete. Ready for
SCHEMA-LOCKED.md marker commit once user signs off on revised doc.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Substrate thesis requires a single source of truth before parallel work
streams (UI/Atoms/Graph/Runtime) can proceed independently without drift.
This document is that SSoT.
Key decisions baked in (open to revision before lock):
- Atom = one verb on a primitive, not one crate. Target ~150 atoms
across current 25 crates. Crate = physical container, atom = unit of
composition.
- File layout: src/atoms/<verb>.rs (code) + atoms/<verb>.md (docs with
machine-parseable YAML frontmatter) + atoms/schemas/*.json (JSON
Schema draft-07 for input/output) + capabilities.toml (auto-generated
aggregator, committed to repo).
- Atom kinds: command / query / stream / transform. Combined with
side_effects[] and idempotent flag, runtime decides retry safety,
parallelism, caching.
- Naming: <crate>::<verb> globally unique. Rust :: separator keeps it
native-feeling.
- Versioning: atoms inherit crate SemVer. Breaking change to an atom =
new atom (create-v2), old marked deprecated.
- Runtime contract: `kei-runtime invoke <atom-id> --input <json>` with
schema validation at entry + exit, ledger row per invocation.
- Graph contract: kei-sage auto-walks atoms/*.md, resolves [[atom-id]]
wikilinks, exposes rank / related / search / graph over atom corpus.
- UI contract: kei-forge web wizard generates .md + .json + .rs + test
from form input; postcondition cargo check + kei-schema-lint pass.
Document declares 4 stream interfaces explicitly — each stream knows
what it reads from this schema, what it writes, what it does NOT depend
on from other streams. Enables true parallel work.
6 open questions flagged for user review at bottom:
1) JSON Schema draft-07 vs 2020-12
2) Atom ID separator :: vs /
3) side_effects strings vs structured
4) capabilities.toml committed vs gitignored
5) kei-atom-template in this PR or defer to Stream A
6) Error model per-atom vs shared registry
STATUS: DRAFT — awaits user approval + SCHEMA-LOCKED.md marker before
parallel streams start. Once locked, breaking changes require explicit
revocation + all-streams sync.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two production-readiness fixes motivated by the v0.22.2 post-mortem.
1. aarch64-linux: native ARM runner instead of cross-compile
v0.22.2 consistently failed `Install aarch64 cross-linker` (apt
gcc-aarch64-linux-gnu) on the ubuntu-latest x86_64 runner. Was
carried as `experimental: true` so non-blocking, but meant no
aarch64-linux Rust tarball ever shipped.
Fix: move to ubuntu-24.04-arm (native ARM64 runner). Rust builds
aarch64-unknown-linux-gnu HOST-NATIVELY — no cross-linker, no
`.cargo/config.toml` linker override. `experimental: false` now —
native path is reliable.
2. Publish step: softprops/action-gh-release → `gh release create` CLI
v0.22.2 softprops/action-gh-release v2.6.2 uploaded all 15 assets
successfully but exited with `failure` due to a metadata-update
race: asset uploaded to GitHub's blob store, then the subsequent
PATCH to set the asset's `name` returned 404 because the Releases
metadata API hadn't caught up yet (eventual consistency). Workflow
failure → Release left in Draft. We had to promote it manually
(`gh release edit --draft=false`) and re-upload one missing sha256.
Fix: replace the action with `gh release create` + `gh release
upload --clobber` in a bash step.
- Idempotent: existing release gets updated in place.
- No metadata PATCH race: CLI never patches, it creates fresh.
- Retry loop: up to 3 tries per asset on transient network errors.
- `--clobber` means re-runs replace cleanly.
- GitHub CLI is pre-installed on every runner, zero new deps.
Verified post-polish on v0.22.2: 16/16 assets present, Release
Published, `kei-mcp-server-darwin-arm64` + `keisei` both execute on
this MacBook (arm64) — adapter list shows Claude Code detected at
project+user scope. SHA256 of `keisei-aarch64-apple-darwin.tar.gz`
verified OK.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Root cause: macos-13 Intel Mac runners were deprecated by GitHub. The
darwin-x64 bun matrix job was sitting queued for 1.5-2.5 hours on every
tag push (v0.21.1, v0.22.0, v0.22.1) and never picked up a runner. The
release job has `needs: [build-release, build-mcp-binary]` so it waited
forever — NO GitHub Releases were created for any v0.22 tag.
Fix: bun cross-compiles to every target (Linux / macOS / Windows,
x64 / arm64) from any host via `--target=<bun-target>`. Consolidate the
entire build-mcp-binary matrix onto ubuntu-latest. Binaries remain
native per-target (correct Mach-O / ELF / PE format preserved by bun
--target flag).
Side effects:
- Faster: Linux runners provision in seconds vs macOS in minutes
- No macOS quota cost (free tier: 2000 min/month, macOS = 10x multiplier)
- No runner starvation on tag push
- `continue-on-error` arm64-linux carve-out removed (no longer needed —
all jobs now on the same runner pool with equal reliability)
Verified locally: bun 1.1+ supports all 5 target triples from Linux host.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Merge of feat/v0.22-keisei-schema-v4 into main (which already had
Track C's fs_type tests) elided '); }' at 2 seams. Tests compiled
once I added them back, but the edit missed the git-add step.
No behaviour change — both tests already passed after the fix;
commit just closes out the working tree.
+670 LOC to README.md. Source-of-truth extraction from each primitive's
actual src/main.rs (clap subcommands) + hook header comments + skill
SKILL.md frontmatter.
Covers:
- Rust primitives (25) with real subcommands, flags, state paths,
exit codes. Extracted from src/main.rs.
- Shell primitives (13) with usage signature + env-var contract.
- Hooks (10) tabular + per-hook detail (event/severity/bypass).
- Skills (39) grouped into 6 collapsible <details> sections.
- keisei CLI deep-dive — real flag matrix, exit codes, env vars,
SSoT location, v0.19 hardening invariants.
Agent flagged 4 discrepancies vs prior task-description drafts
(agent refused to fabricate: no --client / --force / --dry-run on
keisei, exit codes 0/1 not 0/1/2, kei-curator --db required).
These were never in the code — docs now describe reality.
bash scripts/regen-counts.sh --check: no drift
wc -l README.md: 1233
Closes user request 'сделай подробное описание каждой функции'.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
