@cleocode/skills 2026.10.17 → 2026.10.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.10.17",
+  "version": "2026.10.18",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-dev-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-dev-workflow
 description: Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.
-version: 3.1.20
+version: 3.1.22
 protocol: contribution
 dependencies: []
 sharedResources:
@@ -14,7 +14,7 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.1.20
+  version: 3.1.22
   tier: core
   install: harness
   covers:
@@ -26,7 +26,7 @@ metadata:
     - packages/core/src/hooks.ts
     - packages/core/templates/git-hooks/**
     - packages/contracts/src/git-hooks.ts
-  lastReviewed: 2026-10-15
+  lastReviewed: 2026-10-16
   stability: stable
 ---
 
@@ -509,13 +509,11 @@ Provider delivery receives canonical SDK file reads and Git discovery through a
 Adapters do not acquire a runtime dependency on core for these utilities.
 
 Project business rules live in tracked `.cleo/hooks.json`; generated provider entries
-are delivery outputs. Until the hooks-v1 stable promotion, a stable build is inert (T13557):
-`cleo hook sync --activate` refuses with `E_HOOKS_V1_UNRELEASED`, existing receipts report
-`unreleased` and never run (a required `--ci` check fails), and `--disable` still works; a
-`-canary.N` build or the promotion's `cleo.releasedFeatures` stamp opens the gate
-(`core/src/hooks/release-gate.ts`). A source checkout carries a stable version, so hooks
-cannot be activated on main either; only code passing the gate's `allowUnreleased` option
-(tests) opts in. Preview with `cleo hook sync --dry-run`; explicit local activation
+are delivery outputs. hooks-v1 was promoted in v2026.10.17 and is released in source
+(T13776), so every build activates and runs project hooks. The release gate
+(`core/src/hooks/release-gate.ts`, T13557) stays for a future hook feature: while one is
+unreleased, `cleo hook sync --activate` refuses with `E_HOOKS_V1_UNRELEASED` and existing
+receipts report `unreleased` and never run. Preview with `cleo hook sync --dry-run`; explicit local activation
 uses `cleo hook sync --activate` and binds definitions, handlers and dependencies to
 current hashes. Source drift requires reactivation and runs no handler: Git, worktree, direct
 and CI refuse (naming `cleo hook sync --activate`) every event bound by the approved bindings
@@ -533,6 +531,20 @@ Launcher faults allow locally regardless of checker error policy. File inputs an
 provider records use bounded regular-file reads; FIFOs are rejected. Unsupported
 provider bindings remain unsupported in delivery summaries, including mixed bindings.
 
+The Stop event has ONE CLEO entry per provider, `cleo hook stop --provider claude-code|codex`
+(T13796), in order goal tick → ask-enforce → session end. The goal runtime goes first, only when
+`.opencode/goals/` exists (`CLEO_GOAL_TICK_COMMAND`, default `ocg tick`, Stop JSON on stdin,
+JSON-only stdout, at most 60 s, its process group SIGKILLed at the deadline): a block is
+re-serialised as exactly `{decision, reason}` (reason capped) and skips the rest. Next, an ask-enforce block (T13420) wins and keeps
+the session open, because the agent still owes the owner an ask. Otherwise Claude Code's runs
+`cleo session end --quiet` as before; Codex's never ends the session (its Stop fires every turn
+and never did). Every step fails open to the session end (missing, failing or timed-out tick;
+ask-enforce error); `CLEO_GOAL_TICK=off` skips the tick; `CLEO_ASK_ENFORCE=off` or heavy-command
+mode `off` (`CLEO_HEAVY_COMMAND_HOOK` / `resources.heavyCommandHook`, read at run time) skips the
+ask check, as they removed its separate hook before.
+Sync folds the separate ask-enforce and old session-end Stop entries into it in place; Codex's
+rides the heavy-command mode, Claude Code's always stays.
+
 Init, upgrade and inspection share the commit-msg, pre-commit and pre-push installer.
 Git determines effective hooksPath and the common directory, including linked worktrees.
 Exact known template hashes or local receipts authorize refresh; a marker alone does

package/skills/ct-lean/SKILL.md

@@ -4,17 +4,20 @@ description: >-
   Lean change discipline for CLEO work: the smallest change that fully solves the task, and
   a reply a busy owner understands in one read. Use on every coding task (writing, fixing,
   refactoring, reviewing, choosing dependencies) and when the owner asks for the simplest
-  solution, YAGNI, or complains about over-engineering or bloat. Never trades away evidence
+  solution, YAGNI, or complains about over-engineering or bloat; also for a lean code review
+  ("review this", "review my PR") or a whole-repo audit ("audit the repo", "what can I
+  delete"). Never trades away evidence
   gates, package boundaries, validation, data safety or anything the task asked for.
 license: MIT
 metadata:
-  version: 1.2.0
+  version: 1.4.0
   tier: core
   install: harness
   covers:
     - packages/core/src/orchestration/lean-change.ts
     - packages/cleo/src/cli/commands/lean.ts
     - packages/core/src/orchestration/lean-debt.ts
+    - packages/core/src/orchestration/lean-gain.ts
   lastReviewed: 2026-10-13
   stability: stable
   attribution: Adapted from Ponytail 5.1.0 by DietrichGebert (MIT) — https://github.com/DietrichGebert/ponytail
@@ -39,6 +42,8 @@ The level resolves from `CLEO_LEAN_LEVEL`, then the session level, then the `lea
 config key, then `full`. When the owner asks for a level ("go ultra", "lean off"), set it:
 `cleo lean level ultra --session` for this session, `cleo lean level lite` for the project,
 `--global` for every project. `cleo lean level` alone shows the level and its source.
+`cleo lean gain --card` shows the measured benchmark scoreboard: averages, never a number
+for this repo.
 
 ## Before you write
 
@@ -104,7 +109,9 @@ never in the reply (CLEO-INJECTION.md universal protocol step 7).
 
 - `references/examples.md` — worked CLEO examples, over-built vs lean.
 - `references/never-cut.md` — the never-cut list with the gate that enforces each row.
-- `references/reviewing.md` — a lean review checklist for PRs and your own diff.
+- `references/review.md` — review a change: correct, safe, load, tested, fast, lean, on
+  `cleo nexus` callers and blast radius; numbered four-part findings and a verdict.
+- `references/audit.md` — audit a whole repo the same way, on `cleo map` and `cleo nexus`.
 
 ---
 

package/skills/ct-lean/__tests__/review-audit.test.ts

@@ -0,0 +1,57 @@
+/**
+ * T13665 — ct-lean review and audit workflows: Ponytail parity on CLEO's code
+ * graph. Pins the priorities, the four-part finding contract, the nexus-backed
+ * caller and dead-code checks, and the MIT attribution.
+ *
+ * @task T13665
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel: string) => readFileSync(join(skillRoot, rel), 'utf-8');
+
+describe.each(['references/review.md', 'references/audit.md'])('ct-lean %s (T13665)', (rel) => {
+  // Markdown wraps lines anywhere, including inside bold; compare on single spaces.
+  const text = read(rel).replace(/\s+/g, ' ');
+
+  it('keeps the priority order and the four-part finding contract', () => {
+    expect(text).toContain('correct, safe, holds under load, tested, fast, lean');
+    for (const part of ['What this is', 'Problem', 'Fix', 'If we skip it']) {
+      expect(text).toMatch(new RegExp(`\\*\\*${part}:?\\*\\*`));
+    }
+    for (const group of ['Must fix', 'Should fix', 'Nice to have']) {
+      expect(text).toMatch(new RegExp(`\\*\\*${group}:?\\*\\*`));
+    }
+    expect(text).toContain('Verdict');
+    expect(text).toContain('Not checked:');
+  });
+
+  it('checks callers and unused code with cleo nexus, never an empty impact alone', () => {
+    expect(text).toContain('cleo nexus impact <symbol>');
+    expect(text).toContain('cleo nexus status');
+    expect(text).toMatch(/\*\*and\*\* (no string|a grep)/);
+  });
+
+  it('treats a named shortcut as a decision and points at cleo lean debt', () => {
+    expect(text).toContain('`shortcut:`');
+    expect(text).toContain('cleo lean debt');
+  });
+
+  it('credits Ponytail under its MIT license', () => {
+    expect(text).toContain('Ponytail 5.1.0');
+    expect(text).toContain('MIT');
+    expect(read('LICENSE-ponytail')).toContain('MIT License');
+  });
+});
+
+describe('ct-lean SKILL.md points at both workflows (T13665)', () => {
+  it('lists review.md and audit.md, not the old checklist', () => {
+    const skill = read('SKILL.md');
+    expect(skill).toContain('references/review.md');
+    expect(skill).toContain('references/audit.md');
+    expect(skill).not.toContain('references/reviewing.md');
+  });
+});

package/skills/ct-lean/references/audit.md

@@ -0,0 +1,82 @@
+# Audit a whole repo with ct-lean
+
+Audit the repo like the senior developer who just inherited it and gets paged when it
+breaks. Order of importance: **correct, safe, holds under load, tested, fast, lean**. The
+owner asked for a report, so give it in full. Use this for "audit this codebase", "find
+bloat", "what can I delete". It is a one-shot report that changes nothing.
+
+Adapted from Ponytail 5.1.0's `ponytail-audit` (DietrichGebert, MIT; see
+`../LICENSE-ponytail`), rebuilt on CLEO's code graph and project map.
+
+## 1. Map first
+
+- Audit what the owner names: a folder, a package, or the whole repo. Nothing named: the
+  whole repo.
+- Survey with `cleo map` (stack, architecture, structure, conventions, testing,
+  integrations, concerns). `cleo map --focus concerns` goes straight to the risky parts.
+- Check the code graph is fresh with `cleo nexus status`; re-index with
+  `cleo nexus analyze` if it is stale and you may.
+- See how the code hangs together with `cleo nexus clusters` (communities) and
+  `cleo nexus flows` (execution flows). Read the main flows end to end: user input, money,
+  auth, data writes, background jobs, anything shared between processes.
+- Find the expected load (README, deploy config) and say which load you assumed.
+- In a big repo, go deep where a mistake costs the most, not file by file. Say which parts
+  you did not read.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case, callers that disagree with what a
+   function returns, the same rule applied differently in two places.
+2. **Risk:** security holes, privacy (one user's data reaching another), data loss. In
+   CLEO: DB opens or table writes outside the chokepoint, swallowed errors, self-attested
+   evidence.
+3. **Scale:** check-then-write races, the same work done by every process, memory that only
+   grows, a query per item, O(n²) on big input, per-process state that must be shared.
+4. **Missing test:** risky logic with no test that fails when it breaks. One good test, not
+   coverage.
+5. **Speed:** big slowdowns are problems; small wins are suggestions.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, flags and config, speculative features
+   - reuse: two helpers doing the same thing (keep one, name the path)
+   - stdlib / native: a dependency doing what a few lines or the platform can do
+   - yagni: an interface with one implementation, a factory with one product, a wrapper
+     that only passes calls through
+   - merge: near-copies that must change together
+   - split: one function or class doing several unrelated jobs (split by job, never by
+     line count)
+   - boundary: code in the wrong package (see the AGENTS.md package table)
+
+## 3. Check before you report
+
+- Every finding needs a concrete case. No case, no finding.
+- Before calling code unused: `cleo nexus impact <symbol>` shows no callers **and** a grep
+  of the whole tree (tests, fixtures, config, string and dynamic references) finds none.
+  An empty impact alone never proves it unused.
+- A `shortcut:` (or older `ponytail:`) comment that names its limit is a decision, not a
+  finding, unless the expected load already crosses it. `cleo lean debt` lists them; one
+  with no upgrade trigger is worth a line.
+- Propose the smallest fix that works. Prefer fixes that delete code.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English. Start with `What this repo does:` in two or three sentences, and the
+load you assumed.
+
+Then the findings in three groups, most important first, skipping empty groups: **Must
+fix** (bug, security, privacy, data loss, breaks at the expected load), **Should fix**
+(risky code without a test, real slowness, duplication, mixed jobs, code that should not
+exist), **Nice to have** (small speed-ups, shorter forms).
+
+Number findings across all groups, at most 20; if you left smaller ones out, say how many.
+Every finding has four parts (**What this is**, **Problem**, **Fix**, **If we skip it**),
+each one or two short sentences, with its `path:line`.
+
+End with:
+- `Verdict:` one line: healthy, or what to fix first.
+- `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
+- `Not checked:` the parts you did not read or could not run.
+
+Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and one line on what
+you checked. The audit changes no code. In CLEO, file each serious finding as a task so it
+does not stay only in chat.

package/skills/ct-lean/references/review.md

@@ -0,0 +1,100 @@
+# Review a change with ct-lean
+
+Review a change like the senior developer who gets paged when it breaks. Order of
+importance: **correct, safe, holds under load, tested, fast, lean**. Lean still matters:
+every extra line must be read, tested and fixed later. The owner asked for a report, so
+give it in full. Use this for "review this", "review my PR", "review the last commit",
+and for your own diff before `cleo verify`.
+
+Adapted from Ponytail 5.1.0's `ponytail-review` (DietrichGebert, MIT; see
+`../LICENSE-ponytail`), rebuilt on CLEO's code graph and evidence rules.
+
+## 1. Understand first
+
+- Review what the owner names: uncommitted or staged changes, a branch, a PR, or files.
+  Nothing named: the uncommitted changes, or the last commit if there are none.
+- Check the code graph is fresh with `cleo nexus status`. A stale index means its answers
+  below are incomplete; say so under **Not checked**.
+- Read the diff, then the code it touches. For every changed function, run
+  `cleo nexus context <symbol>` (callers, callees, the flows it belongs to) and
+  `cleo nexus impact <symbol>` (blast radius). These are parsed from source, so they are
+  exact where grep guesses. Static analysis cannot see dynamic or string references, so
+  also grep for the name before you claim nothing else calls it.
+- For a PR or commit range, `cleo nexus diff` shows new and removed relations and broken
+  call chains between the two commits.
+- Trace the real flow: where data comes in, what is stored, what goes out.
+- Find the expected load in the repo (README, deploy config): one person running a script,
+  or many users and processes at once. Judge scale against it and say which load you assumed.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item, rounding, time
+   zones), a caller broken by the change, a fix in one caller while the shared function
+   stays broken.
+2. **Risk:** security holes (injection, weak randomness, secrets, unchecked user input),
+   privacy (one user's data reaching another), data loss (swallowed errors, writes in the
+   wrong order, no transaction). In CLEO: a raw DB open or table write outside the
+   chokepoint, a `catch (err: unknown)`, an evidence gate self-attested.
+3. **Scale:** fine for one user, wrong for many: check-then-write races, the same work done
+   by every process, memory or lists that only grow, a query per item, O(n²) on big input,
+   per-process state that must be shared.
+4. **Missing test:** risky new logic (a branch, a parser, money, security, a data write, a
+   bug fix) with no test that fails when it breaks. One good test, not coverage.
+5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot loop) are
+   suggestions.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, speculative features
+   - reuse: the repo already has this helper, contract or chokepoint (name the path)
+   - stdlib / native: the platform already does it; a new dependency for a few lines
+   - yagni: an abstraction with one implementation, config nobody sets
+   - merge: near-copies that must change together
+   - split: one function doing several unrelated jobs. Split by job, never by line count.
+   - boundary: code in the wrong package (see the AGENTS.md package table)
+
+## 3. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this wrong
+  result". No case, no finding.
+- Re-read the lines and confirm: the caller exists (`cleo nexus context`), the value can
+  really be empty, the code really is unused (no callers in `cleo nexus impact` **and** no
+  string or dynamic reference in a grep).
+- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit
+  is a decision, not a finding, unless the expected load already crosses it.
+  `cleo lean debt` lists them all.
+- Propose the smallest fix that works. Prefer fixes that delete code. Never add layers,
+  frameworks or config the problem does not need.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English: short sentences, everyday words. Explain a technical term the first
+time you use it.
+
+Start with `What this change does:` in two or three sentences.
+
+Then the findings in three groups, skipping empty groups:
+- **Must fix:** bug, security, privacy, data loss, breaks at the expected load.
+- **Should fix:** risky code without a test, real slowness, duplication, a function that
+  mixes jobs, code that should not exist.
+- **Nice to have:** small speed-ups, shorter forms.
+
+Number findings across all groups, so the owner can say "fix 2 and 5". Every finding has
+four parts, each one or two short sentences:
+
+2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+   - **What this is:** At midnight this job closes the day and bills all orders of that day.
+   - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+     at 00:30 in Berlin is billed on the day before.
+   - **Fix:** Compute the day once in the shop's time zone. One line, nothing else changes.
+   - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+End with:
+- `Verdict: Ship.` or `Verdict: fix 1 and 3 first.`
+- `Lean: -<N> lines possible.` when lean findings exist.
+- `Not checked:` one line, if something mattered and you could not check it (a stale
+  `cleo nexus status`, an untested path, a harness you could not run).
+
+Nothing found: `What this change does:`, then `Looks good. Ship.` and one line on what you
+checked. The review lists findings and changes no code. In CLEO, file each serious
+finding as a task (`cleo add --type task --parent <epic> --title ... --acceptance "..."`)
+so none stays only in chat.

package/skills/ct-release-orchestrator/SKILL.md

@@ -7,7 +7,7 @@ adrRefs:
   - ADR-063
   - ADR-065
 metadata:
-  version: 3.2.5
+  version: 3.2.6
   tier: on-demand
   install: harness
   covers:
@@ -15,7 +15,7 @@ metadata:
     - packages/core/src/validation/protocols/protocols-markdown/release.md
     - packages/cleo/src/cli/commands/release.ts
   loomStage: release
-  lastReviewed: 2026-10-11
+  lastReviewed: 2026-10-16
   stability: stable
 ---
 
@@ -32,8 +32,9 @@ hotfixes are exempt. The promotion gate runs before GitHub Release creation.
 That plan also makes `scripts/mark-hotfix-release.mjs` stamp
 `cleo.releasedFeatures: ["hooks-v1"]` into `@cleocode/core`, which opens the
 hooks-v1 runtime gate on the stable build (T13557); stable candidates without it
-prove the runtime inert. Remove `hooks-v1` from `UNRELEASED_HOOK_FEATURES` in a
-normal PR after the promotion, before the next stable release.
+prove the runtime inert. hooks-v1 was promoted in v2026.10.17 and is released
+in source since T13776 (`UNRELEASED_HOOK_FEATURES` is empty), so later releases
+need neither the flag nor the stamp.
 `cleo release plan` refuses a stable plan whose source opens that gate since the
 previous tag (`hooks-v1` leaving the set, a changed `hooksV1Released`, a deleted
 gate) with `E_HOOKS_V1_PROMOTION_REQUIRED`, unless it is the promotion or passes

package/skills/manifest.json

@@ -566,7 +566,7 @@
     },
     {
       "name": "ct-dev-workflow",
-      "version": "3.1.20",
+      "version": "3.1.22",
       "description": "Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.",
       "path": "skills/ct-dev-workflow",
       "tier": 0,
@@ -983,8 +983,8 @@
     },
     {
       "name": "ct-lean",
-      "version": "1.2.0",
-      "description": "Lean change discipline for CLEO work: the smallest change that fully solves the task, and a reply a busy owner understands in one read. Use on every coding task (writing, fixing, refactoring, reviewing, choosing dependencies) and when the owner asks for the simplest solution, YAGNI, or complains about over-engineering or bloat. Never trades away evidence gates, package boundaries, validation, data safety or anything the task asked for.",
+      "version": "1.4.0",
+      "description": "Lean change discipline for CLEO work: the smallest change that fully solves the task, and a reply a busy owner understands in one read. Use on every coding task (writing, fixing, refactoring, reviewing, choosing dependencies) and when the owner asks for the simplest solution, YAGNI, or complains about over-engineering or bloat; also for a lean code review (\"review this\", \"review my PR\") or a whole-repo audit (\"audit the repo\", \"what can I delete\"). Never trades away evidence gates, package boundaries, validation, data safety or anything the task asked for.",
       "path": "skills/ct-lean",
       "tier": 0,
       "deliveryTier": "core",
@@ -1168,7 +1168,7 @@
     },
     {
       "name": "ct-release-orchestrator",
-      "version": "3.2.5",
+      "version": "3.2.6",
       "description": "Orchestrates the canonical 4-verb release pipeline introduced by SPEC-T9345: cleo release plan, then cleo release open, then PR + GHA tag workflow, then cleo release reconcile. The deprecated cleo release ship monolith was deleted in T10103 — do not invoke it. Use ship-e2e-smoke to validate the full pipeline end-to-end (dry-run by default). The full verb-to-state map is in docs/release/verb-matrix.md. Use when shipping a new version, validating the release pipeline end-to-end, or promoting a completed epic to released status.",
       "path": "skills/ct-release-orchestrator",
       "tier": 1,

package/skills/ct-lean/references/reviewing.md

@@ -1,22 +0,0 @@
-# Reviewing a diff with ct-lean
-
-Use this when reviewing a PR or your own diff before `cleo verify`.
-
-1. **Scope.** Does every changed file serve the task's acceptance criteria? Name anything
-   that does not, such as an unrelated refactor or a speculative option.
-2. **Reuse.** Was there an existing helper, accessor, contract or chokepoint for this? Check
-   `packages/core/src` and `packages/contracts/src`. A new utility that duplicates one is a
-   finding.
-3. **Abstraction.** Count the new interfaces, options, config keys and wrappers. Each one
-   needs a caller today; "for later" is a finding.
-4. **Completeness.** Grep the callers of every changed exported symbol. A caller, fixture or
-   doc left behind is a finding. Lean never means half-done.
-5. **Root cause.** Is a bug fixed in the shared code, or patched at one call site?
-6. **Checks.** New non-trivial logic has one focused test. Test expectations were not edited
-   to match broken code.
-7. **Never-cut list.** Validation, data safety, security, evidence, type safety, package
-   boundary: confirm none were trimmed to shorten the diff.
-8. **Shortcuts.** Each known limit carries `shortcut: <limit>, <when to upgrade>`.
-
-Report findings as the reply format says: verdict first, then one line per finding with its
-file and line, then what you did not check.