Cognition-OS/REVIEW.md

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.