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.