mmolloy/Cognition-OS
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feature/ledger-prototype #1

Merged
mmolloy merged 6 commits from shadowmo/Cognition-OS:feature/ledger-prototype into main 2026-02-28 06:07:22 +00:00
Conversation 0 Commits 6 Files Changed 8 +39
1 changed files with 39 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit ec9d3d5a4e - Show all commits

39
REVIEW.md Normal file
View File

@@ -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.