asdf

REVIEW.md

@@ -0,0 +1,39 @@
+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.