40 lines
3.2 KiB
Markdown
40 lines
3.2 KiB
Markdown
Cognition-OS — Review & Onboarding Report
|
||
|
||
Summary
|
||
- Purpose: spec + reference design for a "cognitive kernel" (deterministic control plane) and userland services that schedule probabilistic workers. Focus: capability-based security, provenance, deterministic routing.
|
||
- Main components: docs/ (design + RFCs), spec/ (contracts), kernel/ (supervisor stub in Go), runtime/ (placeholder services), linux/ & freebsd/ mappings, examples/ for flows.
|
||
|
||
Sanity checks
|
||
- Repo is largely design/spec. A runnable Go stub exists at kernel/supervisor-go/main.go and builds with module present (go.mod included).
|
||
- README accurately describes intent and recommended reading order.
|
||
- No CI, no tests, no dependency vulnerability tooling detected. Build steps not documented for the Go stub.
|
||
|
||
Top actionable issues (priority order)
|
||
1) Missing CI (tests/build): no GitHub/Gitea CI config found. Add pipeline to `go build ./...` for kernel/supervisor-go. (kernel/supervisor-go/main.go)
|
||
2) No CONTRIBUTING checklist for local dev build/test of Go stub — add build/run steps. (CONTRIBUTING.md)
|
||
3) No unit/integration tests: kernel/supervisor-go has logic (hash, ledger append) that should be covered by tests. Add tests for computeHash, Append, and ledger integrity. (kernel/supervisor-go/*.go)
|
||
4) Logger / error handling: Append() returns errors but main ignores them; surface errors to caller and fail-fast during startup. (kernel/supervisor-go/main.go, Append call sites)
|
||
5) Use of map[string]any canonicalization: current canonicalJSON is a best-effort; document risks and add tests for deterministic hashing across Go versions. (kernel/supervisor-go/canonicalJSON)
|
||
6) File permissions for ledger files: open with 0644; consider user/umask and possible sensitive data (use 0600 or configurable). (kernel/supervisor-go/Ledger.Append)
|
||
7) Missing LICENSE clarity for contribution process — LICENSE exists but recommend adding contributor CLA or short note in CONTRIBUTING.md. (CONTRIBUTING.md)
|
||
8) Empty/runtime placeholders under runtime/ — mark TODOs and minimal interface docs so contributors know the intended contracts. (runtime/*)
|
||
9) .DS_Store remnants exist under freebsd/prototypes — remove these artifacts. (freebsd/prototypes/.DS_Store)
|
||
10) Lack of automated formatting/linting configuration (gofmt, go vet) — add Makefile/CI step. (repo root)
|
||
|
||
Recommended first 3 tasks for a new contributor
|
||
1) Add CI build for Go stub (effort: 1–2 hours)
|
||
- Create simple pipeline that runs `go test ./...` and `go build ./kernel/supervisor-go`.
|
||
2) Write unit tests for computeHash & Ledger.Append (effort: 4–6 hours)
|
||
- Test deterministic outputs for canonical inputs and ledger append behavior. Include temp files and cleanup.
|
||
3) Document local dev steps (effort: 1 hour)
|
||
- Update CONTRIBUTING.md with build/run/test commands, Go version, and how to run the supervisor stub.
|
||
|
||
Quick wins (low effort)
|
||
- Remove .DS_Store, add .gitattributes and .editorconfig, add Makefile with build/test targets.
|
||
|
||
Next steps I can take
|
||
- Create branch work/review, commit this REVIEW.md, push branch, and open a merge request draft. (ready to run)
|
||
- Optionally add a basic GitLab/Gitea CI config for Go build/test.
|
||
|
||
Prepared by: lab-code-heavy (automated review) — tell me to push this review to work/review and open the MR.
|