@cleocode/cleo 2026.4.154 → 2026.4.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.4.154",
+  "version": "2026.4.158",
   "description": "CLEO CLI — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -29,16 +29,16 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
-    "@cleocode/caamp": "2026.4.154",
-    "@cleocode/contracts": "2026.4.154",
-    "@cleocode/cant": "2026.4.154",
-    "@cleocode/lafs": "2026.4.154",
-    "@cleocode/nexus": "2026.4.154",
-    "@cleocode/playbooks": "2026.4.154",
-    "@cleocode/runtime": "2026.4.154"
+    "@cleocode/caamp": "2026.4.158",
+    "@cleocode/cant": "2026.4.158",
+    "@cleocode/lafs": "2026.4.158",
+    "@cleocode/nexus": "2026.4.158",
+    "@cleocode/contracts": "2026.4.158",
+    "@cleocode/playbooks": "2026.4.158",
+    "@cleocode/runtime": "2026.4.158"
   },
   "peerDependencies": {
-    "@cleocode/core": "2026.4.154"
+    "@cleocode/core": "2026.4.158"
   },
   "peerDependenciesMeta": {
     "@cleocode/core": {

package/templates/hooks/commit-msg

@@ -0,0 +1,73 @@
+#!/bin/sh
+# CLEO_MANAGED_HOOK v1
+# T1588 — project-agnostic T-ID enforcement for every commit subject.
+#
+# Rule: subject MUST contain `T<digits>` somewhere, OR be a merge/revert
+# (which preserves the git merge --no-ff path established in T1587 and the
+# stock `git revert` flow).
+#
+# Override: `git commit --no-verify` bypasses (standard git behaviour).
+# A best-effort audit of `--no-verify` lives in the git shim (see T1591) —
+# hooks themselves cannot observe `--no-verify`.
+#
+# This script is POSIX `/bin/sh` only (no bash/zsh-isms). It MUST work in
+# any environment cleo init runs in: node-less projects, Rust, Python,
+# bare repos, etc. Do not introduce node/pnpm dependencies here.
+set -e
+
+MSG_FILE="$1"
+if [ -z "$MSG_FILE" ] || [ ! -f "$MSG_FILE" ]; then
+  echo "cleo commit-msg hook: missing message file argument" >&2
+  exit 1
+fi
+
+# First non-empty, non-comment line = the subject.
+SUBJECT=""
+while IFS= read -r line || [ -n "$line" ]; do
+  case "$line" in
+    '#'*) continue ;;
+  esac
+  trimmed=$(printf '%s' "$line" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ -n "$trimmed" ]; then
+    SUBJECT="$trimmed"
+    break
+  fi
+done < "$MSG_FILE"
+
+if [ -z "$SUBJECT" ]; then
+  echo "cleo commit-msg hook: empty commit subject — refusing." >&2
+  exit 1
+fi
+
+# Bypass merge / revert / fixup / squash / amend-only metadata commits.
+case "$SUBJECT" in
+  'Merge '*) exit 0 ;;
+  'Revert '*) exit 0 ;;
+  'fixup! '*) exit 0 ;;
+  'squash! '*) exit 0 ;;
+  'amend! '*) exit 0 ;;
+esac
+
+# Match `T` followed by 1+ digits anywhere in the subject.
+# POSIX BRE — `[0-9][0-9]*` is `\d+` equivalent.
+if printf '%s' "$SUBJECT" | grep -Eq 'T[0-9]+'; then
+  exit 0
+fi
+
+cat >&2 <<EOF
+cleo commit-msg hook: commit subject is missing a task ID.
+
+  subject: $SUBJECT
+
+Every commit MUST reference at least one CLEO task. Examples:
+
+  feat(T1588): ship POSIX commit-msg hook
+  T1588 — wire hooks-install into cleo init
+  fix: T1588 typo
+
+Override (audited via git shim — see T1591):
+
+  git commit --no-verify
+
+EOF
+exit 1

package/templates/hooks/pre-push

@@ -0,0 +1,87 @@
+#!/bin/sh
+# CLEO_MANAGED_HOOK v1
+# T1588 — project-agnostic T-ID enforcement for every commit being pushed.
+#
+# git invokes this with `<remote> <url>` as args and feeds ref updates on
+# stdin: `<local-ref> <local-sha> <remote-ref> <remote-sha>` (one per line).
+#
+# For each new commit being pushed (commits in `local-sha` that are NOT
+# already in any remote ref), require a T-ID in the subject. Same allow-
+# list as commit-msg: merge / revert / fixup / squash / amend.
+#
+# Override: `git push --no-verify` (standard git override).
+#
+# T1595:reconcile-extension-point
+# Pre-push reconcile gate hooks here (see T1595 worker).
+# Reserved range below — DO NOT remove these markers; T1595 extends here.
+# T1595:reconcile-extension-point-end
+#
+# POSIX `/bin/sh` only. No node/pnpm dependency.
+set -e
+
+ZERO_SHA="0000000000000000000000000000000000000000"
+EMPTY_TREE_SHA=""
+FAIL=0
+FAIL_LOG=""
+
+check_subject() {
+  subject="$1"
+  case "$subject" in
+    'Merge '*) return 0 ;;
+    'Revert '*) return 0 ;;
+    'fixup! '*) return 0 ;;
+    'squash! '*) return 0 ;;
+    'amend! '*) return 0 ;;
+  esac
+  if printf '%s' "$subject" | grep -Eq 'T[0-9]+'; then
+    return 0
+  fi
+  return 1
+}
+
+# Read each ref-update line from stdin.
+while read -r local_ref local_sha remote_ref remote_sha; do
+  # Branch deletion (push :branch) — nothing to validate.
+  if [ "$local_sha" = "$ZERO_SHA" ]; then
+    continue
+  fi
+
+  if [ "$remote_sha" = "$ZERO_SHA" ]; then
+    # New branch: validate every commit reachable from local_sha that is
+    # NOT reachable from any other remote ref.
+    range="$local_sha --not --remotes"
+  else
+    range="$remote_sha..$local_sha"
+  fi
+
+  # Subject extraction: %s = subject. NUL-delimit for safety.
+  # shellcheck disable=SC2086
+  commits=$(git rev-list $range 2>/dev/null || true)
+  for sha in $commits; do
+    subject=$(git log -1 --pretty=%s "$sha" 2>/dev/null || true)
+    if [ -z "$subject" ]; then
+      continue
+    fi
+    if ! check_subject "$subject"; then
+      FAIL=1
+      FAIL_LOG="${FAIL_LOG}  ${sha}  ${subject}
+"
+    fi
+  done
+done
+
+if [ "$FAIL" -ne 0 ]; then
+  cat >&2 <<EOF
+cleo pre-push hook: refusing push — commits are missing task IDs.
+
+${FAIL_LOG}
+Every commit MUST reference at least one CLEO task (e.g. \`T1588\`).
+Fix the subjects (\`git rebase -i\` + reword), or override with:
+
+  git push --no-verify
+
+EOF
+  exit 1
+fi
+
+exit 0

package/templates/hooks/pre-push.t1595-extension.sh

@@ -0,0 +1,140 @@
+#!/bin/sh
+# T1595 — pre-push reconcile gate (extension)
+#
+# This file is the reconcile-gate extension for the project's pre-push
+# hook. T1588 will produce a unified pre-push hook that contains a
+# sentinel block:
+#
+#   # T1595:reconcile-extension-point
+#   # Pre-push reconcile gate hooks here (see T1595 worker)
+#
+# When T1588 lands, the contents of `reconcile_gate()` below MUST be
+# inlined at that sentinel. Until then, this file is sourced as-is by
+# any pre-push hook that wants the reconcile gate (see installer in
+# `packages/core/src/hooks/install-pre-push.ts`, future).
+#
+# CONTRACT
+#   - POSIX shell (`/bin/sh`); no bashisms.
+#   - Reads pending tag from `git tag --sort=-v:refname | head -1`
+#     (tag-shape agnostic — works for CalVer or SemVer).
+#   - Calls `cleo reconcile release --tag <pending> --dry-run --json`
+#     and parses the aggregate `reconciled` count.
+#   - Drift > 0 → exit 1 with task-ID list.
+#   - Drift == 0 → return 0.
+#   - Override: env `CLEO_ALLOW_DRIFT_PUSH=1` bypasses the gate AND
+#     appends an audit entry to
+#     `${XDG_DATA_HOME:-$HOME/.local/share}/cleo/audit/drift-push-bypass.jsonl`.
+#   - Project-agnostic: no hardcoded branch name; default branch is
+#     resolved via `git symbolic-ref refs/remotes/origin/HEAD` when
+#     needed.
+#
+# EXIT CODES
+#   0  — no drift, push allowed
+#   1  — drift detected, push refused (or cleo CLI unavailable in
+#        strict mode; see CLEO_RECONCILE_STRICT below)
+#
+# CONFIGURATION (env)
+#   CLEO_ALLOW_DRIFT_PUSH=1   bypass the gate (audited)
+#   CLEO_RECONCILE_STRICT=1   if `cleo` CLI is missing, refuse push
+#                             (default: warn-and-allow so first-time
+#                              clones without cleo installed still work)
+#   CLEO_RECONCILE_BIN=<path> override the cleo binary path (testing)
+
+set -eu
+
+reconcile_gate() {
+  # Locate cleo CLI ------------------------------------------------------
+  cleo_bin="${CLEO_RECONCILE_BIN:-cleo}"
+  if ! command -v "$cleo_bin" >/dev/null 2>&1; then
+    if [ "${CLEO_RECONCILE_STRICT:-0}" = "1" ]; then
+      echo "ERROR: cleo CLI not found on PATH (strict mode)" >&2
+      echo "       install cleo or unset CLEO_RECONCILE_STRICT" >&2
+      return 1
+    fi
+    # Soft-fail: warn but allow push. Avoids blocking fresh clones.
+    echo "warn: cleo CLI not found; skipping reconcile gate" >&2
+    return 0
+  fi
+
+  # Resolve the pending release tag -------------------------------------
+  # We use the most recent tag as the "pending" anchor. Reconcile is
+  # project-agnostic — it walks tasks released_in this tag's range
+  # regardless of CalVer vs SemVer shape.
+  pending_tag="$(git tag --sort=-v:refname 2>/dev/null | head -n 1 || true)"
+  if [ -z "$pending_tag" ]; then
+    # No tags yet → no release to reconcile.
+    return 0
+  fi
+
+  # Override path -------------------------------------------------------
+  if [ "${CLEO_ALLOW_DRIFT_PUSH:-0}" = "1" ]; then
+    audit_dir="${XDG_DATA_HOME:-$HOME/.local/share}/cleo/audit"
+    mkdir -p "$audit_dir"
+    audit_log="$audit_dir/drift-push-bypass.jsonl"
+    ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    user="${USER:-${LOGNAME:-unknown}}"
+    repo="$(git rev-parse --show-toplevel 2>/dev/null || echo unknown)"
+    head_sha="$(git rev-parse HEAD 2>/dev/null || echo unknown)"
+    # Write a JSONL line. Stay project-agnostic: no jq dependency.
+    printf '{"ts":"%s","user":"%s","repo":"%s","head":"%s","tag":"%s","reason":"CLEO_ALLOW_DRIFT_PUSH=1"}\n' \
+      "$ts" "$user" "$repo" "$head_sha" "$pending_tag" >> "$audit_log"
+    echo "warn: pre-push reconcile gate bypassed (CLEO_ALLOW_DRIFT_PUSH=1)" >&2
+    echo "      audit: $audit_log" >&2
+    return 0
+  fi
+
+  # Run reconcile in dry-run JSON mode ----------------------------------
+  # We swallow non-zero exit codes from the CLI here because reconcile
+  # exits 2 when drift exists; we want to read the JSON regardless.
+  json_out="$("$cleo_bin" reconcile release --tag "$pending_tag" --dry-run --json 2>/dev/null || true)"
+  if [ -z "$json_out" ]; then
+    if [ "${CLEO_RECONCILE_STRICT:-0}" = "1" ]; then
+      echo "ERROR: cleo reconcile release returned empty output (strict mode)" >&2
+      return 1
+    fi
+    echo "warn: cleo reconcile release returned empty output; skipping gate" >&2
+    return 0
+  fi
+
+  # Parse the aggregate `reconciled` count without jq.
+  # The InvariantReport JSON has a top-level `"reconciled": N` integer.
+  # We grep the first such key (top-level always emitted before per-result
+  # entries). Per-result entries are nested under `results[*].details`,
+  # so the first match is the aggregate.
+  drift_count="$(printf '%s' "$json_out" \
+    | grep -o '"reconciled"[[:space:]]*:[[:space:]]*[0-9]\+' \
+    | head -n 1 \
+    | grep -o '[0-9]\+' \
+    || true)"
+  drift_count="${drift_count:-0}"
+
+  if [ "$drift_count" -gt 0 ] 2>/dev/null; then
+    echo "ERROR: pre-push reconcile gate detected drift" >&2
+    echo "       tag: $pending_tag" >&2
+    echo "       drift count: $drift_count shipped-but-pending task(s)" >&2
+    # Best-effort: extract reconciled task IDs from results[*].details.reconciled
+    # arrays. Strings look like "T1411" (project-agnostic prefix).
+    drifted_ids="$(printf '%s' "$json_out" \
+      | tr -d '\n' \
+      | grep -o '"reconciled"[[:space:]]*:[[:space:]]*\[[^]]*\]' \
+      | grep -o '"[A-Za-z][A-Za-z0-9_-]*"' \
+      | sort -u \
+      | tr '\n' ' ' \
+      || true)"
+    if [ -n "$drifted_ids" ]; then
+      echo "       drifted tasks: $drifted_ids" >&2
+    fi
+    echo "" >&2
+    echo "Refuse push: run 'cleo reconcile release --tag $pending_tag' to" >&2
+    echo "reconcile, or set CLEO_ALLOW_DRIFT_PUSH=1 (audited bypass)." >&2
+    return 1
+  fi
+
+  return 0
+}
+
+# When sourced from the unified pre-push hook the function is invoked
+# at the sentinel point. When run standalone (testing), invoke directly.
+if [ "${T1595_SOURCED:-0}" != "1" ]; then
+  reconcile_gate
+fi