@cleocode/core 2026.8.2 → 2026.8.3

package/templates/CLEO-INJECTION.md

@@ -127,7 +127,7 @@ CLEO has **three distinct relationship systems**. Do not conflate them.
 |------|---------|
 | Check session | `cleo session status` |
 | Resume context | `cleo briefing` |
-| Start session | `cleo session start --scope global` |
+| Start session | `cleo session start --scope global --name "<what you are doing>"` (both flags are REQUIRED) |
 | End session | `cleo session end --note "..."` |
 <!-- /CLEO-INJECTION:section=session-commands -->
 
@@ -151,29 +151,44 @@ Memory context: `cleo memory digest --brief` gives a live project memory summary
 <!-- CLEO-INJECTION:section=nexus -->
 ## Nexus — when to use which scope
 
-`cleo nexus` is the code-intelligence surface. It has **5 scopes**. Pick by intent, not name.
-
-| Intent                                      | Scope          | First-reach command                     |
-|---------------------------------------------|----------------|-----------------------------------------|
-| Edit/refactor *this* repo safely            | `project`      | `cleo nexus impact <symbol>`            |
-| Explore *this* repo by concept or symbol    | `project`      | `cleo nexus query` / `context`          |
-| One-shot machine-readable repo snapshot     | `project`      | `cleo nexus report` (LAFS JSON)         |
-| Recall what the agent knows across sessions | `living-brain` | `cleo nexus brain find "<q>"`           |
-| Compare or share patterns across repos      | `cross-project`| `cleo nexus compare` / `shared`         |
-| Blend code + memory + cross-repo            | `hybrid`       | `cleo nexus synthesize <topic>`         |
-| Index health / reindex / purge              | `global-infra` | `cleo nexus admin <status|analyze|clean>` |
-
-**Project resolution** (project + hybrid scopes only):
-`--project-id` > `--path` > `cwd`. Default ID = `base64url(path).slice(0,32)`.
-
-**Every nexus envelope returns**:
-- `meta.scope` — confirms which scope answered
-- `meta.projectId` — confirms which project (if applicable)
-- `meta.suggestedNext: string[]` — chained-reasoning hints (use these before re-discovering)
-
-**Rule**: BEFORE editing any symbol, run `cleo nexus impact <symbol>`. HIGH/CRITICAL = stop and warn.
-
-**Skip the help dump**: `cleo nexus report` answers most agent project-questions in one call.
+`cleo nexus` is the code-intelligence surface over THIS repo's symbol graph.
+Pick by intent. Every command below is verified to exist — see the gate note.
+
+| Intent                                    | Command                          |
+|-------------------------------------------|----------------------------------|
+| **Check the index before trusting it**    | `cleo nexus status`              |
+| Blast radius before editing a symbol      | `cleo nexus impact <symbol>`     |
+| Callers / callees / community of a symbol | `cleo nexus context <symbol>`    |
+| Everything about one symbol in one call   | `cleo nexus full-context <symbol>` |
+| Find a symbol by code text                | `cleo nexus search-code "<text>"` |
+| Symbols touched by a task                 | `cleo nexus task-symbols <taskId>` |
+| Why does this symbol exist / who needs it | `cleo nexus why <symbol>`        |
+| Detected communities / execution flows    | `cleo nexus clusters` / `flows`  |
+| Rebuild the index                         | `cleo nexus analyze`             |
+
+**FIRST CALL IS `cleo nexus status`.** It returns `nodeCount`, `lastIndexedAt`
+and `staleFileCount`. The index is NOT auto-refreshed — a symbol added after
+the last `analyze` run is simply absent, and a lookup for it returns
+`E_NOT_FOUND` that reads identically to "no such symbol". If `staleFileCount`
+is a large fraction of `fileCount`, run `cleo nexus analyze` or treat
+`git grep` as the ground truth and SAY SO in your response.
+
+`E_NOT_FOUND` from `impact`/`context` now reports the index size, its median
+entry age, and the repair command. Read it — do not infer that nexus is broken.
+
+**Project resolution**: `--project-id` > `--path` > `cwd`.
+Default ID = `base64url(path).slice(0,32)`.
+
+**Rule**: BEFORE editing any symbol, run `cleo nexus impact <symbol>`.
+HIGH/CRITICAL = stop and warn. If the index is stale, say that instead of
+silently substituting `git grep`.
+
+> Commands named here are asserted against the live CLI by
+> `scripts/lint-injection-commands.mjs` (T12069). Five commands previously
+> listed in this section — `nexus report`, `nexus brain find`, `nexus compare`,
+> `nexus shared`, `nexus synthesize`, plus `nexus admin` — never existed; the
+> gate exists so a protocol that every agent is told to follow can no longer
+> drift from the binary.
 <!-- /CLEO-INJECTION:section=nexus -->
 
 <!-- CLEO-INJECTION:section=orchestration -->
@@ -372,7 +387,7 @@ Every spawn prompt contains these required sections — orchestrators can progra
 ## Rules
 
 - No time estimates — use `small`, `medium`, `large` sizing
-- Token budget: avoid `cleo list` without `--parent`, avoid `cleo help --tier 2` before tier 0
+- Token budget: avoid `cleo list` without `--parent`; get usage from `cleo <command> --help` (there is no top-level help command)
 - Do not read full task details for tasks you won't work on
 <!-- /CLEO-INJECTION:section=rules -->
 

package/templates/workflows/release-prepare.yml.tmpl

@@ -40,6 +40,10 @@ on:
         description: 'Epic task ID (e.g. T9999) used by `cleo release plan`'
         type: string
         required: false
+      tasks:
+        description: 'Comma-separated task IDs (e.g. T101,T102) used by `cleo release plan` when the release is task-scoped rather than epic-scoped'
+        type: string
+        required: false
       channel:
         description: 'Release channel'
         type: choice
@@ -310,11 +314,24 @@ jobs:
           PLAN_FILE=".cleo/release/${{ inputs.version }}.plan.json"
           if [ -z "${{ inputs.plan-blob-sha256 }}" ]; then
             echo "No plan-blob-sha256 input — generating fresh plan."
-            EPIC_ARGS=()
+            # T12089: `cleo release plan` REQUIRES a scope (--saga | --epic |
+            # --tasks). This branch previously passed none whenever `epic` was
+            # empty, so `plan` exited 2 and every release died here at
+            # "Prepare bump-PR" — after a full green preflight. Forward whichever
+            # scope the dispatcher supplied, and if none was, say so plainly
+            # instead of surfacing an argparse error from a nested command.
+            SCOPE_ARGS=()
             if [ -n "${{ inputs.epic }}" ]; then
-              EPIC_ARGS=(--epic "${{ inputs.epic }}")
+              SCOPE_ARGS+=(--epic "${{ inputs.epic }}")
             fi
-            cleo release plan "${{ inputs.version }}" "${EPIC_ARGS[@]}" --json > "$PLAN_FILE"
+            if [ -n "${{ inputs.tasks }}" ]; then
+              SCOPE_ARGS+=(--tasks "${{ inputs.tasks }}")
+            fi
+            if [ ${#SCOPE_ARGS[@]} -eq 0 ]; then
+              echo "::error::No release scope supplied. Dispatch with 'epic' or 'tasks' (cleo release plan requires --saga, --epic or --tasks), or pass plan-blob-sha256 with a committed plan file."
+              exit 1
+            fi
+            cleo release plan "${{ inputs.version }}" "${SCOPE_ARGS[@]}" --json > "$PLAN_FILE"
           else
             echo "Verifying pre-computed plan against sha256=${{ inputs.plan-blob-sha256 }}"
             if [ ! -f "$PLAN_FILE" ]; then
@@ -330,27 +347,46 @@ jobs:
           echo "plan_file=$PLAN_FILE" >> "$GITHUB_OUTPUT"
         timeout-minutes: 5
 
-      # R-205(c): bump version files via `cleo version-bump`.
+      # R-205(c): bump every package manifest to the release version.
+      #
+      # T12093: this step used to run `cleo version-bump`, a command that has
+      # NEVER existed — the verb is absent from the CLI manifest, so the step
+      # died with `Unknown command version-bump` (exit 127) on every dispatch,
+      # always AFTER a full green preflight (~20 min). Version bumping is
+      # project-shaped (single package vs workspace), so it is a placeholder:
+      # override with `versionBumpCmd` in `.cleo/release-config.json`.
       - name: Bump version
-        run: cleo version-bump --version "${{ inputs.version }}"
+        run: |
+          VERSION="${{ inputs.version }}"
+          {{VERSION_BUMP_CMD}}
         timeout-minutes: 3
 
-      # R-205(d): regenerate CHANGELOG via the preserved `cleo release
-      # changelog` primitive, scoped to commits since the previous tag.
-      - name: Regenerate CHANGELOG
-        run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          if [ -n "$PREV_TAG" ]; then
-            cleo release changelog --since "$PREV_TAG"
-          else
-            cleo release changelog
-          fi
+      # R-205(d): CHANGELOG.md.
+      #
+      # T12093: this step used to run `cleo release changelog`, which also does
+      # not exist (`cleo release` has no `changelog` sub-verb). CHANGELOG.md is
+      # written by `cleo release plan` itself (T9838), so there is nothing to
+      # regenerate here — the correct action is to VERIFY the section is present
+      # and fail loudly if it is not, rather than silently ship a release whose
+      # notes were never written.
+      - name: Verify CHANGELOG section
+        run: cleo release validate-changelog "${{ inputs.version }}"
         timeout-minutes: 3
 
       # R-205(e): commit with the canonical subject line.
+      #
+      # T12093: `git commit` exits 1 on an empty index, so an already-prepared
+      # version failed here with a bare "nothing to commit" and no explanation.
+      # An empty prepare cannot become a PR either (`gh pr create` rejects a head
+      # with no commits ahead of base), so say what state the repo is in and what
+      # to do next instead of pushing a branch that cannot open.
       - name: Commit prepare
         run: |
           git add -A
+          if git diff --cached --quiet; then
+            echo "::error::Nothing to commit — every package.json and CHANGELOG.md already match ${{ inputs.version }} on main. This release is already prepared; tag it directly (git tag -a ${{ inputs.version }} && git push origin ${{ inputs.version }}) instead of re-running prepare."
+            exit 1
+          fi
           git commit -m "release: prepare ${{ inputs.version }}"
         timeout-minutes: 2
 
@@ -362,6 +398,27 @@ jobs:
         timeout-minutes: 5
 
       # R-205(f): open the bump-PR via `gh pr create`.
+      #
+      # T12093: the body was `--body-file <plan>.json`, so every bump-PR opened
+      # with a raw schema envelope as its description. The plan already carries
+      # the rendered notes at `meta.releaseNotes` (the same text that lands in
+      # CHANGELOG.md) — use that, and fall back to the JSON only if absent.
+      - name: Render PR body
+        id: body
+        run: |
+          node -e '
+            const fs = require("node:fs");
+            const plan = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+            const notes = plan?.meta?.releaseNotes;
+            fs.writeFileSync(
+              "/tmp/bump-pr-body.md",
+              typeof notes === "string" && notes.trim().length > 0
+                ? notes
+                : "```json\n" + JSON.stringify(plan, null, 2) + "\n```\n",
+            );
+          ' "${{ steps.plan.outputs.plan_file }}"
+        timeout-minutes: 2
+
       - name: Open bump-PR
         run: |
           gh pr create \
@@ -369,7 +426,7 @@ jobs:
             --head "${{ steps.branch.outputs.name }}" \
             --title "release: prepare ${{ inputs.version }}" \
             --label "{{PR_LABEL}}" \
-            --body-file "${{ steps.plan.outputs.plan_file }}"
+            --body-file /tmp/bump-pr-body.md
         timeout-minutes: 5
 
       # R-209(c): emit recovery hint into the job summary artifact.