@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/migrations/2026-04-25-t991-parent-link-repair.js

@@ -0,0 +1,76 @@
+/**
+ * One-shot migration: repair T991 BRAIN Integrity epic parent-child DB links.
+ *
+ * ## Background
+ *
+ * The T991 epic shipped all 8 child tasks (T992-T999) in v2026.4.98, but the
+ * `parent_id` column was never populated in tasks.db. The Council 2026-04-24
+ * audit (T1216/T1227) confirmed `schema-artifact-not-work-defect` — all work
+ * is real; only the DB relationship is missing.
+ *
+ * ## Git evidence
+ *
+ * Release commit: `18128e3cec6b61f7486c136fb9a2cd956c51b37c`
+ * Subject: `chore(release): v2026.4.98 — T991 + T1000 + T1007 Tier 2 + T1013 hygiene`
+ *
+ * Individual child commits:
+ *   - T993: `738d4bd1a` — feat(core/T993): Check A0 title-prefix blocklist in verifyAndStore gate
+ *   - T994: `fb59ba1fa` — feat(core/T994): correlateOutcomes Step 9a.5 + trackMemoryUsage lifecycle wiring
+ *   - T995: `8493fc351` — feat(core/T995): Step 9f hard-sweeper DELETE prune_candidate=1 AND quality<0.2
+ *   - T996: `0de82f872` — feat(sentient/T996): dream cycle migrated to tick loop
+ *   - T997: `71c2f2ff1` + `0c417d0ce` — feat/fix(cleo/T997): promote-explain CLI + registry registration
+ *   - T998: `9abc54d2e` — feat(T998): nexus_relations plasticity columns + strengthenNexusCoAccess Step 6b
+ *   - T999: `fe6dcd26a` — feat(core/T999): memory-bridge mode flag (cli default)
+ *
+ * T992 evidence: documented in CHANGELOG.md under release v2026.4.98.
+ *
+ * ## Repair strategy
+ *
+ * Use `cleo update <id> --parent T991` for each child — the canonical write path
+ * per AGENTS.md (no direct SQLite). Each call is idempotent: re-running when
+ * parent_id is already T991 produces no change.
+ *
+ * ## Usage
+ *
+ * Run the companion script directly:
+ *   ```
+ *   node scripts/repair-t991-parent-links.mjs
+ *   node scripts/repair-t991-parent-links.mjs --dry-run
+ *   ```
+ *
+ * @task T1419
+ * @epic T991
+ * @see scripts/repair-t991-parent-links.mjs
+ */
+/** The parent epic task ID. */
+export const PARENT_EPIC_ID = 'T991';
+/**
+ * Child task IDs that should be linked as children of T991.
+ * Source: CHANGELOG v2026.4.98 + Council audit T1227 verdict.
+ */
+export const CHILD_TASK_IDS = [
+    'T992',
+    'T993',
+    'T994',
+    'T995',
+    'T996',
+    'T997',
+    'T998',
+    'T999',
+];
+/** Git evidence anchors supporting the parent-child relationships. */
+export const GIT_EVIDENCE = {
+    releaseCommit: '18128e3cec6b61f7486c136fb9a2cd956c51b37c',
+    releaseTag: 'v2026.4.98',
+    childCommits: {
+        T993: '738d4bd1adbea2a9ee45f12ba51ab652320f529e',
+        T994: 'fb59ba1fa1852d4b7c9f00cdf96d497fe0b45b1f',
+        T995: '8493fc351563ce3e0da023fe4a8b0dd23a4d7ee4',
+        T996: '0de82f872878eedf8b33a5496d5fdaf7976723c6',
+        T997a: '71c2f2ff160ae68fca5d3002d771ea5724fc4dc1',
+        T997b: '0c417d0cea6165f8e25a30aca65b7c7f4555ca85',
+        T998: '9abc54d2e31d59fa1fdeae4827879019c5cb848c',
+        T999: 'fe6dcd26afa01ff123926c9243dc5c654b781b07',
+    },
+};
+//# sourceMappingURL=2026-04-25-t991-parent-link-repair.js.map

package/dist/migrations/2026-04-25-t991-parent-link-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"2026-04-25-t991-parent-link-repair.js","sourceRoot":"","sources":["../../src/migrations/2026-04-25-t991-parent-link-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,+BAA+B;AAC/B,MAAM,CAAC,MAAM,cAAc,GAAG,MAAe,CAAC;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;CACE,CAAC;AAIX,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa,EAAE,0CAA0C;IACzD,UAAU,EAAE,YAAY;IACxB,YAAY,EAAE;QACZ,IAAI,EAAE,0CAA0C;QAChD,IAAI,EAAE,0CAA0C;QAChD,IAAI,EAAE,0CAA0C;QAChD,IAAI,EAAE,0CAA0C;QAChD,KAAK,EAAE,0CAA0C;QACjD,KAAK,EAAE,0CAA0C;QACjD,IAAI,EAAE,0CAA0C;QAChD,IAAI,EAAE,0CAA0C;KACjD;CACO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.4.158",
+  "version": "2026.5.0",
   "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.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"
+    "@cleocode/caamp": "2026.5.0",
+    "@cleocode/lafs": "2026.5.0",
+    "@cleocode/cant": "2026.5.0",
+    "@cleocode/contracts": "2026.5.0",
+    "@cleocode/runtime": "2026.5.0",
+    "@cleocode/playbooks": "2026.5.0",
+    "@cleocode/nexus": "2026.5.0"
   },
   "peerDependencies": {
-    "@cleocode/core": "2026.4.158"
+    "@cleocode/core": "2026.5.0"
   },
   "peerDependenciesMeta": {
     "@cleocode/core": {

package/templates/HANDOFF-REDIRECT-STUB.md

@@ -0,0 +1,37 @@
+# STALE — DO NOT READ THIS FILE FOR STATE
+
+**This file is deprecated as canonical state per T1593 (shipped in v2026.4.157).**
+
+The current state of the project lives in **TASKS + BRAIN** — never in markdown.
+
+## What you must do instead
+
+```bash
+cleo briefing
+```
+
+That command returns:
+- The structured `lastSession.handoff.note` — guaranteed current, written at session-end
+- `nextTasks` ranked by score — the system's recommendation for what to work on
+- `blockedTasks` showing dependency chains — what cannot start yet
+- `memoryContext` with relevant BRAIN observations
+- `activeEpics` with completion percentages
+
+## If you are seeing this and you ALREADY started reading instead of running `cleo briefing`
+
+Stop. Run `cleo briefing`. Then `cleo memory find "IRONCLAD-ROADMAP"` if needed.
+The system has explicit instructions for the next orchestrator that do NOT live in this file.
+
+## Verification
+
+Run any of these to verify state from the canonical source:
+
+```bash
+cleo briefing                        # next-session handoff (canonical)
+cleo dash                            # task counts
+cleo memory find "roadmap"           # roadmap observations in BRAIN
+```
+
+---
+
+*This file deliberately contains no state. Reading it cannot mislead you. Run `cleo briefing`.*

package/templates/hooks/commit-msg

@@ -1,11 +1,18 @@
 #!/bin/sh
 # CLEO_MANAGED_HOOK v1
 # T1588 — project-agnostic T-ID enforcement for every commit subject.
+# T1608 — diff-scope validation: warn when staged files drift from task scope.
 #
 # 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).
 #
+# Diff-scope check (T1608): if `cleo` is on the PATH and the referenced task
+# has a non-empty files[] array, compare the staged diff against that scope.
+# If >50 % of staged files fall outside the task's declared scope, emit a
+# WARNING on stderr — but still exit 0 (hard-block is intentionally omitted
+# to avoid rejecting valid refactors; the warning feeds audit tooling).
+#
 # 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`.
@@ -13,6 +20,7 @@
 # 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.
+# The diff-scope check degrades gracefully when cleo or python3 is absent.
 set -e
 
 MSG_FILE="$1"
@@ -50,11 +58,8 @@ 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
+if ! printf '%s' "$SUBJECT" | grep -Eq 'T[0-9]+'; then
+  cat >&2 <<EOF
 cleo commit-msg hook: commit subject is missing a task ID.
 
   subject: $SUBJECT
@@ -70,4 +75,139 @@ Override (audited via git shim — see T1591):
   git commit --no-verify
 
 EOF
-exit 1
+  exit 1
+fi
+
+# -----------------------------------------------------------------------
+# T1608: diff-scope validation (warning-only — exits 0 on all paths below)
+# -----------------------------------------------------------------------
+# Extract the first T-ID from the subject (e.g. "feat(T1608): ..." → T1608).
+TASK_ID=$(printf '%s' "$SUBJECT" | grep -Eo 'T[0-9]+' | head -n 1)
+
+# Resolve cleo binary: prefer explicit CLEO_BIN env, then PATH lookup.
+CLEO_BIN="${CLEO_BIN:-}"
+if [ -z "$CLEO_BIN" ]; then
+  CLEO_BIN=$(command -v cleo 2>/dev/null || true)
+fi
+
+if [ -z "$CLEO_BIN" ] || [ ! -x "$CLEO_BIN" ] || [ -z "$TASK_ID" ]; then
+  # cleo not available or no T-ID extracted — skip diff-scope check.
+  exit 0
+fi
+
+# Resolve python3 (used for JSON parsing — lightweight, no npm required).
+PYTHON3_BIN=$(command -v python3 2>/dev/null || true)
+if [ -z "$PYTHON3_BIN" ]; then
+  # python3 unavailable — skip diff-scope check gracefully.
+  exit 0
+fi
+
+# Fetch task.files[] via cleo show. Suppress errors (task may not exist
+# in cleo DB for the target project; non-zero cleo exit → skip silently).
+TASK_JSON=$("$CLEO_BIN" show "$TASK_ID" 2>/dev/null) || true
+if [ -z "$TASK_JSON" ]; then
+  exit 0
+fi
+
+# Extract the files[] array as one path per line via python3 -c.
+# Using -c avoids the stdin-conflict that arises with heredoc + pipe.
+TASK_FILES=$("$PYTHON3_BIN" -c "
+import json, sys
+try:
+    d = json.loads(sys.argv[1])
+    files = d.get('data', {}).get('task', {}).get('files', [])
+    print('\n'.join(f for f in files if f))
+except Exception:
+    pass
+" "$TASK_JSON" 2>/dev/null) || true
+
+if [ -z "$TASK_FILES" ]; then
+  # Task has no files[] scope declared — nothing to validate against.
+  exit 0
+fi
+
+# Get staged file list (diff-scope is only meaningful for staged changes).
+# git diff --cached exits 0 even when empty, so this is always safe.
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null) || true
+
+if [ -z "$STAGED_FILES" ]; then
+  # No staged files (e.g. amend of message only) — skip check.
+  exit 0
+fi
+
+# Count staged files and how many are in-scope (path prefix or exact match).
+# A staged file is "in-scope" when it matches any task file path OR any
+# task file path is a path-prefix of the staged file (directory scope).
+# We delegate the maths to python3 to avoid shell integer-division quirks.
+# Both TASK_FILES and STAGED_FILES are passed as argv to avoid stdin conflict.
+DRIFT_RESULT=$("$PYTHON3_BIN" -c "
+import sys
+
+# argv[1] = newline-separated task files; argv[2] = newline-separated staged files
+task_files = [f.strip() for f in sys.argv[1].splitlines() if f.strip()]
+staged = [f.strip() for f in sys.argv[2].splitlines() if f.strip()]
+
+def in_scope(staged_path, task_files):
+    for tf in task_files:
+        # Exact match.
+        if staged_path == tf:
+            return True
+        # task file is a directory prefix of the staged file.
+        if staged_path.startswith(tf.rstrip('/') + '/'):
+            return True
+        # staged file is a directory prefix of a task file (task file
+        # is deeper; e.g. task scope is src/foo.ts, staged is src/).
+        if tf.startswith(staged_path.rstrip('/') + '/'):
+            return True
+    return False
+
+if not staged or not task_files:
+    print('SKIP')
+    sys.exit(0)
+
+out_of_scope = [f for f in staged if not in_scope(f, task_files)]
+total = len(staged)
+drift_count = len(out_of_scope)
+drift_pct = (drift_count * 100) // total if total > 0 else 0
+
+print('TOTAL=' + str(total))
+print('DRIFT_COUNT=' + str(drift_count))
+print('DRIFT_PCT=' + str(drift_pct))
+for f in out_of_scope:
+    print('OUT=' + f)
+" "$TASK_FILES" "$STAGED_FILES" 2>/dev/null) || true
+
+# Parse drift result.
+if [ -z "$DRIFT_RESULT" ] || printf '%s' "$DRIFT_RESULT" | grep -q '^SKIP$'; then
+  exit 0
+fi
+
+DRIFT_PCT=$(printf '%s' "$DRIFT_RESULT" | grep '^DRIFT_PCT=' | sed 's/^DRIFT_PCT=//')
+TOTAL=$(printf '%s' "$DRIFT_RESULT" | grep '^TOTAL=' | sed 's/^TOTAL=//')
+DRIFT_COUNT=$(printf '%s' "$DRIFT_RESULT" | grep '^DRIFT_COUNT=' | sed 's/^DRIFT_COUNT=//')
+OUT_FILES=$(printf '%s' "$DRIFT_RESULT" | grep '^OUT=' | sed 's/^OUT=//')
+
+# Threshold: warn when drift exceeds 50 % (i.e. drift_pct > 50).
+THRESHOLD=50
+if [ -n "$DRIFT_PCT" ] && [ "$DRIFT_PCT" -gt "$THRESHOLD" ] 2>/dev/null; then
+  cat >&2 <<EOF
+cleo commit-msg hook [T1608]: diff-scope drift WARNING
+
+  Task   : $TASK_ID
+  Staged : $TOTAL file(s) — $DRIFT_COUNT ($DRIFT_PCT%) are outside $TASK_ID scope
+
+  Out-of-scope staged files:
+$(printf '%s' "$OUT_FILES" | sed 's/^/    /')
+
+  Task scope (files[]):
+$(printf '%s' "$TASK_FILES" | sed 's/^/    /')
+
+  This is a WARNING, not a hard block. The commit will proceed.
+  To silence: ensure staged files align with the task scope,
+  or add the files to the task via \`cleo update $TASK_ID --files ...\`.
+
+EOF
+  # Exit 0 — warning only.
+fi
+
+exit 0