@cleocode/cleo 2026.4.5 → 2026.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.4.5",
+  "version": "2026.4.7",
   "description": "CLEO CLI — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -13,12 +13,12 @@
   },
   "dependencies": {
     "citty": "^0.2.1",
-    "@cleocode/caamp": "2026.4.5",
-    "@cleocode/cant": "2026.4.5",
-    "@cleocode/core": "2026.4.5",
-    "@cleocode/lafs": "2026.4.5",
-    "@cleocode/contracts": "2026.4.5",
-    "@cleocode/runtime": "2026.4.5"
+    "@cleocode/cant": "2026.4.7",
+    "@cleocode/contracts": "2026.4.7",
+    "@cleocode/caamp": "2026.4.7",
+    "@cleocode/core": "2026.4.7",
+    "@cleocode/lafs": "2026.4.7",
+    "@cleocode/runtime": "2026.4.7"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -31,7 +31,8 @@
     "dist",
     "migrations",
     "completions",
-    "bin"
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",

package/templates/cleoos-hub/README.md

@@ -0,0 +1,34 @@
+# CleoOS Hub Bundle
+
+This directory contains the seed assets for the **CleoOS Hub**, the
+operator-global, cross-project workspace that lives under `$CLEO_HOME`
+(typically `~/.local/share/cleo/` on Linux).
+
+These files ship with `@cleocode/cleo` and are copied into the operator's
+home directory by `ensureCleoOsHub()` on first run. The copy is **never
+overwriting**: any human or agent edits to the installed files are
+preserved across upgrades.
+
+## Layout
+
+```
+templates/cleoos-hub/
+├── pi-extensions/      # Pi extensions (CANT-aware orchestration helpers)
+│   ├── orchestrator.ts # Wave-based parallel orchestrator
+│   ├── stage-guide.ts  # Stage-aware lifecycle guidance loader
+│   └── cant-bridge.ts  # Bridge between CANT workflows and Pi tooling
+└── global-recipes/     # Global Justfile Hub
+    ├── justfile        # Cross-project recipe library
+    └── README.md       # Authoring/runner conventions
+```
+
+## Editing rules
+
+- These are **template seeds**, not the runtime copies. Operators edit the
+  installed copies under `$CLEO_HOME`, not these.
+- Updates to these templates only reach existing installs when the
+  installed files are missing — if they exist, they are kept as-is to
+  preserve user/agent edits. Use `cleo upgrade --include-global` followed
+  by manual reconciliation if you intentionally want to refresh them.
+- The Pi extensions are validated source — do not patch them in place
+  without bumping the @cleocode/cleo package version.

package/templates/cleoos-hub/global-recipes/README.md

@@ -0,0 +1,46 @@
+# CleoOS Global Recipes Hub
+
+This directory is the Single Source of Truth for cross-project automation
+**recipes** — shell commands that any agent can invoke regardless of which
+project it's working in.
+
+## The three-way SSoT split (Phase 4 alignment)
+
+CleoOS separates protocol, workflow, and deterministic automation into
+three distinct representations, each with a dedicated SSoT:
+
+| Purpose | SSoT | Location | Authors |
+|---|---|---|---|
+| **Agent protocols & constraints** | SKILL.md files | `packages/skills/skills/ct-*` | Humans (edit), Chef Agent (propose) |
+| **Agent workflows & hooks** | .cant files | `.cleo/agents/*.cant` + `$CLEO_HOME/cant-workflows` | Humans + agents |
+| **Deterministic automation** | justfile recipes | `$CLEO_HOME/global-recipes/justfile` + project-local | Humans + Chef Agent |
+
+**Do not duplicate protocol text into justfile recipes.** Recipes should
+wrap `cleo` CLI commands that resolve the protocol from skills at runtime.
+
+## Writers
+
+- **Humans** — edit `justfile` and sibling files directly with your editor.
+- **Cleo Chef Agent** — the meta-agent cooks up new recipes via the
+  `pm_upsert_global_recipe` tool binding (available from Phase 3 onward).
+
+## Runners
+
+Agents invoke recipes via the `pm_run_action` tool binding, which resolves to:
+
+    just -f $CLEO_HOME/global-recipes/justfile <recipe> [args...]
+
+Local project `justfile`s still take precedence for project-specific work.
+
+## Naming
+
+- Keep recipe names lowercase-kebab
+- Prefix domain-specific recipes (`rcasd-init`, `schema-validate`)
+- Document every recipe with a comment above the rule
+- Reference skills by name (e.g. `ct-research-agent`) — don't embed prose
+
+## Governance
+
+Context anchoring strictness is enforced per project/global config
+(`cleo config get contextAnchoring.mode`). Default: `block` — recipes that
+reference files or paths not in the BRAIN-anchored inventory will be blocked.

package/templates/cleoos-hub/global-recipes/justfile

@@ -0,0 +1,68 @@
+# CleoOS Global Justfile Hub
+# Cross-project recipe library managed by humans (via editor) and
+# the meta Cleo Chef Agent (via pm_upsert_global_recipe tool).
+#
+# Location: {cleoHome}/global-recipes/justfile
+# Invoke:   just -f $CLEO_HOME/global-recipes/justfile <recipe>
+#
+# ARCHITECTURE (Phase 4 SSoT):
+#   - Protocol text lives in @cleocode/skills (SKILL.md files)
+#   - Recipes here WRAP 'cleo' CLI commands — they don't re-encode protocol
+#   - Stage-specific behavior goes through 'cleo lifecycle guidance <stage>'
+#   - Agent-facing recipes should invoke skills via 'cleo skills info' or
+#     delegate to 'cleo orchestrate spawn <taskId>' which injects skills
+
+# Default: list recipes
+default:
+    @just --list --justfile "{{justfile()}}"
+
+# Bootstrap a new project (greenfield)
+# Invoked by Phase 5 init flow for empty directories.
+bootstrap project-type="node":
+    @echo "[cleoos] bootstrap {{project-type}} — scaffolds CLEO state + loads Tier 0 skills"
+    @test -d .cleo || cleo init
+    @cleo lifecycle guidance research
+
+# Load stage-aware LLM guidance — used by the Cleo Chef Agent and Pi extensions
+stage-guidance stage="research":
+    @cleo lifecycle guidance {{stage}}
+
+# List all available skills (backed by packages/skills/skills/)
+skills:
+    @cleo skills list
+
+# Inspect a specific skill
+skill-info name:
+    @cleo skills info {{name}}
+
+# Dispatch lint for detected project type
+lint:
+    @if test -f package.json; then \
+        if grep -q '"lint"' package.json 2>/dev/null; then \
+            pnpm lint 2>/dev/null || npm run lint; \
+        else \
+            echo "[cleoos] no lint script in package.json"; \
+        fi; \
+    elif test -f Cargo.toml; then \
+        cargo clippy -- -D warnings; \
+    else \
+        echo "[cleoos] no known project type for lint"; \
+    fi
+
+# Dispatch tests for detected project type
+test:
+    @if test -f package.json; then \
+        if grep -q '"test"' package.json 2>/dev/null; then \
+            pnpm test 2>/dev/null || npm test; \
+        else \
+            echo "[cleoos] no test script in package.json"; \
+        fi; \
+    elif test -f Cargo.toml; then \
+        cargo test; \
+    else \
+        echo "[cleoos] no known project type for test"; \
+    fi
+
+# List all recipes across the global hub (convenience alias for discovery)
+recipes:
+    @just --list --justfile "{{justfile()}}"