@cleocode/skills 2026.10.1 → 2026.10.3

package/package.json

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

package/skills/ct-cleo/SKILL.md

@@ -2,14 +2,14 @@
 name: ct-cleo
 description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
 metadata:
-  version: 2.24.3
+  version: 2.24.4
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/session.ts
     - packages/cleo/src/cli/commands/focus.ts
     - packages/cleo/src/cli/commands/sticky.ts
-  lastReviewed: 2026-09-30
+  lastReviewed: 2026-10-01
   stability: stable
 ---
 
@@ -464,4 +464,4 @@ BRAIN ID going forward.
 
 ## Evidence must prove task criteria
 
-Merged PRs and passing CI are provenance. Implementation requires changed artifacts related to the task; testing and review require their own actual results. For tasks with canonical criteria, append explicit links such as `satisfies:T1234#AC1` to each relevant gate's evidence. Fetch the PR merge commit so artifact hashes can be inspected. A changed criterion invalidates its recorded proof. Completing a child preserves an open parent whose own criteria remain unproven; child waivers never transfer to parent criteria.
+Merged PRs and passing CI are provenance. Implementation requires changed artifacts related to the task; testing and review require their own actual results (`ci:<pr>` once the PR merged and the project sets `evidence.ciSatisfies`; else `tool:test-affected` when `testing.affectedCommand` is configured, otherwise a targeted `test-run:<json>` or `tool:test`; plan with `cleo done <id> --plan`, never run the suite by hand and again via `tool:test`). For tasks with canonical criteria, append explicit links such as `satisfies:T1234#AC1` to each relevant gate's evidence. Fetch the PR merge commit so artifact hashes can be inspected. A changed criterion invalidates its recorded proof. Completing a child preserves an open parent whose own criteria remain unproven; child waivers never transfer to parent criteria.

package/skills/ct-ivt-looper/SKILL.md

@@ -6,14 +6,14 @@ adrRefs:
   - ADR-051
   - ADR-061
 metadata:
-  version: 1.0.2
+  version: 1.0.3
   tier: on-demand
   install: harness
   covers:
     - packages/core/src/validation/protocols/cant/testing.cant
     - packages/core/src/validation/protocols/protocols-markdown/testing.md
   loomStage: testing
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-10-01
   stability: stable
 ---
 
@@ -106,7 +106,7 @@ This skill does NOT:
 | `ct-ivt-looper` → `ct-validator` | Loop converged; need to audit the resulting artifacts (e.g. final manifest, spec back-references) against schema/compliance | Emit the convergence manifest entry, then dispatch the `validation` stage |
 | `ct-validator` → `ct-ivt-looper` | Spec is valid but implementation needs dynamic verification | Receive a dispatch from the `validation` stage; iterate the IVT loop on the worktree |
 
-Governance: see **ADR-051** (programmatic gate integrity) which defines the evidence atoms (`tool:test`, `test-run:<json>`) the loop emits and that downstream `cleo verify --gate testsPassed` re-validates, and **ADR-061** (project-agnostic verify tools) which defines the canonical tool-resolution layer.
+Governance: see **ADR-051** (programmatic gate integrity) which defines the evidence atoms (`test-run:<json>`, `tool:test`, `tool:test-affected` where `testing.affectedCommand` is configured — a full `tool:test` then only for root-config changes — and `ci:<pr>` once the PR merged in a project that sets `evidence.ciSatisfies`) the loop emits and that downstream `cleo verify --gate testsPassed` re-validates, and **ADR-061** (project-agnostic verify tools) which defines the canonical tool-resolution layer.
 
 ## Framework Detection
 
@@ -195,6 +195,7 @@ cleo check protocol validation \
 | Deleting assertions to force green | Tests pass but the spec is not met | The skill requires spec-to-test traceability; gaps block convergence |
 | Skipping the validation phase | Lint or type errors slip through | The loop MUST run lint and type check before the test phase every iteration |
 | Treating testing as "just run the tests" | Misses the loop; one-shot runs are not compliant | Testing is a loop, not a single call; record `ivtLoopIterations` |
+| Running the full suite on every iteration | Burns CPU/RAM shared with other agents; the cache misses on every edit | Iterate on the failing or changed test files; record evidence once at the end: `tool:test-affected` when `testing.affectedCommand` is configured, else a targeted `test-run:<json>` or `tool:test`; `ci:<pr>` once the PR merged when the project sets `evidence.ciSatisfies` |
 | Exiting without writing the manifest | Downstream skills cannot see the outcome | Always write the manifest entry — converged or not — before exiting |
 | Reverting the worktree on escalation | Destroys diagnostic evidence | Leave the failed state; the human reviewer needs it |
 
@@ -213,7 +214,7 @@ cleo check protocol validation \
 
 This skill binds to the **testing** LOOM lifecycle stage. Governing ADRs:
 
-- [ADR-051 — programmatic gate integrity](../../../../.cleo/adrs/ADR-051-programmatic-gate-integrity.md) — defines the evidence atoms (`tool:test`, `test-run:<json>`) that the IVT loop emits and that downstream `cleo verify --gate testsPassed` re-validates.
+- [ADR-051 — programmatic gate integrity](../../../../.cleo/adrs/ADR-051-programmatic-gate-integrity.md) — defines the evidence atoms (`test-run:<json>`, `tool:test`, `tool:test-affected` with `testing.affectedCommand`, `ci:<pr>` after merge with `evidence.ciSatisfies`) that the IVT loop emits and that downstream `cleo verify --gate testsPassed` re-validates.
 - [ADR-061 — project-agnostic verify tools](../../../../.cleo/adrs/ADR-061-project-agnostic-verify-tools.md) — defines the canonical tool-resolution layer (`test`, `build`, `lint`, `typecheck`) that the loop walks for framework-agnostic execution.
 
 LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-orchestrator/SKILL.md

@@ -2,13 +2,13 @@
 name: ct-orchestrator
 description: "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \"orchestrate\", \"orchestrator mode\", \"run as orchestrator\", \"delegate to subagents\", \"coordinate agents\", \"spawn subagents\", \"multi-agent workflow\", \"context-protected workflow\", \"agent farm\", \"HITL orchestration\", \"pipeline management\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime."
 metadata:
-  version: 4.0.7
+  version: 4.0.8
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/orchestrate.ts
     - packages/core/src/orchestration/spawn-prompt.ts
-  lastReviewed: 2026-09-29
+  lastReviewed: 2026-10-01
   stability: stable
 ---
 
@@ -330,8 +330,8 @@ files between `verify` and `complete` triggers `E_EVIDENCE_STALE`.
 | Gate | Required atoms |
 |------|---------------|
 | `implemented` | `commit:<sha>` AND `files:<comma-separated>` |
-| `testsPassed` | `tool:pnpm-test` OR `test-run:<vitest-json>` |
-| `qaPassed` | `tool:biome` AND `tool:tsc` (OR `tool:pnpm-build`) |
+| `testsPassed` | `ci:<pr>` once the PR merged, when the project sets `evidence.ciSatisfies`; else `tool:test-affected` when `testing.affectedCommand` is configured; else `test-run:<vitest-json>` OR `tool:test` |
+| `qaPassed` | `ci:<pr>` under the same two conditions; else `tool:biome` AND `tool:tsc` (OR `tool:pnpm-build`) |
 | `documented` | `files:<docs-path>` OR `url:<doc-url>` |
 | `securityPassed` | `tool:security-scan` OR `note:<waiver>` |
 | `cleanupDone` | `note:<summary>` |
@@ -340,14 +340,22 @@ Orchestrator workflow for each completing task:
 
 ```bash
 # 1. Worker reports done with evidence atoms in manifest key_findings
-# 2. Orchestrator runs:
+# 2. Orchestrator plans, then records (cleo done picks affected → ci → full):
+cleo done <taskId> --plan
 cleo verify <taskId> --gate implemented --evidence "commit:$(git rev-parse HEAD);files:<list>"
-cleo verify <taskId> --gate testsPassed --evidence "tool:pnpm-test"
-cleo verify <taskId> --gate qaPassed   --evidence "tool:biome;tool:tsc"
+cleo verify <taskId> --gate testsPassed --evidence "ci:<pr>"   # merged + evidence.ciSatisfies; else tool:test-affected (needs testing.affectedCommand), else tool:test
+cleo verify <taskId> --gate qaPassed   --evidence "ci:<pr>"   # merged + evidence.ciSatisfies; else tool:biome;tool:tsc
 # 3. Close:
 cleo complete <taskId>
 ```
 
+Never re-run a worker's full suite to "double-check": a worker's
+`tool:test-affected` or `tool:test` result for the same tree and the
+same resource limits is a cache hit, and once the PR merges, a project that sets `evidence.ciSatisfies`
+needs no local run at all (`ci:<pr>`). When `testing.affectedCommand` is
+configured, a full `tool:test` is only for changes to root config, which
+affected planning refuses; without it, `tool:test` is the normal run.
+
 Emergency: set `CLEO_OWNER_OVERRIDE=1` and `CLEO_OWNER_OVERRIDE_REASON="<reason>"`
 before the verify call — audited to `.cleo/audit/force-bypass.jsonl`.
 

package/skills/ct-task-executor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-task-executor
 description: General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.
-version: 2.7.6
+version: 2.7.7
 protocol: implementation
 adrRefs:
   - ADR-070
@@ -17,7 +17,7 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 2.7.6
+  version: 2.7.7
   tier: core
   install: harness
   covers:
@@ -28,7 +28,7 @@ metadata:
     - packages/core/src/validation/protocols/cant/implementation.cant
     - packages/core/src/validation/protocols/protocols-markdown/implementation.md
   loomStage: implementation
-  lastReviewed: 2026-09-29
+  lastReviewed: 2026-10-01
   stability: stable
 ---
 

package/skills/ct-task-executor/references/acceptance-criteria-mapping.md

@@ -53,7 +53,7 @@ condition."
 | Count | "with N files", "≥3 entries" | `find -type f | wc -l` |
 | Length/size | "≥50 lines", "≥10K bytes" | `wc -l`, `wc -c` |
 | Linkage | "linked from", "referenced in" | `grep -F` |
-| Tests pass | "all tests pass", "no regressions" | `pnpm run test` |
+| Tests pass | "all tests pass", "no regressions" | `ci:<pr>` after merge (with `evidence.ciSatisfies`); else `tool:test-affected` (with `testing.affectedCommand`), a targeted `test-run:<json>`, or `tool:test` |
 | Lint clean | "biome check passes" | `pnpm biome check .` |
 | Build clean | "compiles", "type-checks" | `pnpm run build && pnpm run typecheck` |
 | Spec match | "satisfies REQ-NNN" | manual trace + test |

package/skills/ct-task-executor/references/anti-patterns.md

@@ -7,19 +7,46 @@ ship work that contains any of these.
 
 ## 1. Test Theater
 
-**Anti-pattern.** Claiming "tests pass" without actually running
-`pnpm run test`.
+**Anti-pattern.** Claiming "tests pass" without programmatic test
+evidence.
 
-**Detection.** Manifest reports `testsPassed: true` but no
-`tool:test` evidence atom; or evidence atom references a stale cache
-key.
+**Detection.** Manifest reports `testsPassed: true` but no `ci:`,
+`tool:test-affected`, `tool:test` or `test-run:` evidence atom; or the
+atom references a stale cache key.
 
 **Cost.** Reviewer must reject and re-spawn the work, doubling the
 token spend on the task.
 
-**Correct pattern.** Always run tests, capture the exit code, and pass
-`--evidence "tool:test"` to `cleo verify`. The cache will skip re-running
-if state is unchanged; running it is free.
+**Correct pattern.** Let the evidence run be the one run:
+
+1. Start with `cleo done <TASK_ID> --plan`. It picks the cheapest valid
+   evidence (affected, then CI, then full) and shows each tool's cache
+   state.
+2. After the PR merges, when the project sets `evidence.ciSatisfies`,
+   record `testsPassed` and `qaPassed` with `ci:<pr>`. No local run is
+   needed.
+3. Otherwise use `tool:test-affected` when `testing.affectedCommand` is
+   configured, else `test-run:<json>` from a targeted run of the test
+   files you changed (or `tool:test`).
+4. While iterating, run only the failing or changed test files.
+
+## 1a. Double Test Runs
+
+**Anti-pattern.** Running `pnpm run test` by hand, then passing
+`tool:test`, which runs the suite again.
+
+**Detection.** A full manual run in the transcript followed by a
+`tool:test` evidence write on the same change.
+
+**Cost.** The manual run records nothing, so the evidence run repeats
+it; only the evidence run's result is cached (and reused for the same
+tree content). With several agents working at once, each double run is
+another full suite competing for CPU and RAM.
+
+**Correct pattern.** Never run the full suite manually. With
+`testing.affectedCommand` configured, run a full `tool:test` only when the
+change touches root config (lockfile, root tsconfig or vitest config),
+which `tool:test-affected` refuses.
 
 ## 2. Workaround Over Root Cause
 

package/skills/ct-task-executor/references/evidence-and-gates.md

@@ -14,8 +14,8 @@ task; the standard set is non-negotiable.
 | Gate | Meaning | Evidence kind |
 |------|---------|---------------|
 | implemented | Code change exists | `commit:<sha>` + `files:<list>` |
-| testsPassed | Tests green | `tool:test` or `test-run:<json>` |
-| qaPassed | Lint + typecheck clean | `tool:lint` + `tool:typecheck` |
+| testsPassed | Tests green | `ci:<pr>` after merge (with `evidence.ciSatisfies`); else `tool:test-affected` (with `testing.affectedCommand`), a targeted `test-run:<json>`, or `tool:test` |
+| qaPassed | Lint + typecheck clean | `ci:<pr>` under the same conditions; else `tool:lint` + `tool:typecheck` |
 | documented | Docs updated | `files:<docs-paths>` |
 | securityPassed | Security scan or waiver | `tool:security-scan` or `note:<rationale>` |
 | cleanupDone | Branch/cleanup summary | `note:<text>` |
@@ -79,13 +79,31 @@ per-`primaryType` fallbacks. Canonical names:
 Legacy aliases still work: `pnpm-test`, `tsc`, `biome`, `cargo-test`,
 `pytest` all map to canonical names.
 
+`tool:test-affected` runs `testing.affectedCommand` over the packages the
+branch diff touches plus their dependents. It refuses (use `tool:test`)
+when the change touches root config or no workspace package. Prefer it
+to `tool:test` before merge. `cleo verify --fresh` bypasses the result
+cache when a cached result is suspect.
+
+### `ci:<pr>`
+
+The merged PR's required CI checks, green on its merge commit (needs
+`evidence.ciSatisfies: true`). Satisfies `testsPassed` and `qaPassed`
+with no local run, so it is the default once the PR has merged.
+
+```bash
+cleo verify T### --gate testsPassed --evidence "ci:1234"
+cleo verify T### --gate qaPassed --evidence "ci:1234"
+```
+
 ### `test-run:<json-path>`
 
 Path to a vitest JSON output file. Re-validated by hash. Preferred for
-sharing test evidence across sibling tasks in the same wave.
+sharing test evidence across sibling tasks in the same wave, and for a
+targeted run of only the test files your change touches.
 
 ```bash
-pnpm vitest run --reporter=json --outputFile=/tmp/vitest-out.json
+pnpm vitest run path/to/changed.test.ts --reporter=json --outputFile=/tmp/vitest-out.json
 cleo verify T### --gate testsPassed --evidence "test-run:/tmp/vitest-out.json"
 ```
 
@@ -108,19 +126,19 @@ they document, they do not prove. Reserve for `cleanupDone`,
 The full per-task ritual, in order:
 
 ```bash
-# 1. Implement and verify locally
+# 1. Implement and verify locally (run only the failing/changed test files)
 pnpm biome check --write .
 pnpm run build && pnpm run typecheck
-pnpm run test
 git add -p && git commit -m "feat(T###): <slug>"
+cleo done T### --plan   # shows the evidence it will use: affected → ci → full
 
 # 2. Capture evidence for each gate (commit SHA from step 1)
 SHA=$(git rev-parse HEAD)
 FILES=$(git diff-tree --no-commit-id --name-only -r HEAD | paste -sd,)
 
 cleo verify T### --gate implemented --evidence "commit:$SHA;files:$FILES"
-cleo verify T### --gate testsPassed --evidence "tool:test"
-cleo verify T### --gate qaPassed --evidence "tool:lint;tool:typecheck"
+cleo verify T### --gate testsPassed --evidence "tool:test-affected"   # needs testing.affectedCommand (else tool:test); merged + evidence.ciSatisfies: ci:<pr>
+cleo verify T### --gate qaPassed --evidence "tool:lint;tool:typecheck"   # merged + evidence.ciSatisfies: ci:<pr>
 cleo verify T### --gate documented --evidence "files:docs/path/to/note.md"
 cleo verify T### --gate securityPassed --evidence "note:no network surface"
 cleo verify T### --gate cleanupDone --evidence "note:branch task/T### ready for merge"
@@ -148,7 +166,9 @@ cleo memory observe "..." --title "..."
 ## Cache Behavior
 
 Tool-evidence results are cached under `.cleo/cache/evidence/<key>.json`,
-keyed on (canonical, cmd, args, HEAD, dirty-tree fingerprint). Parallel
+keyed on (canonical, cmd, args) and the tracked tree content under test:
+two worktrees holding the same content, or a commit, rebase or amend that
+leaves the tree unchanged, share one result. Parallel
 verifies against identical state coalesce to one execution via a per-key
 lock. Cross-worktree parallelism is bounded by a machine-wide per-tool
 semaphore at `~/.local/share/cleo/locks/tool-<canonical>/`.

package/skills/ct-task-executor/references/implementation-patterns.md

@@ -134,10 +134,16 @@ v2026.4.69) in past sessions.
 pnpm biome check --write .   # 1. format + lint
 pnpm run build               # 2. build (includes typecheck via tsc -b)
 pnpm run typecheck           # 3. typecheck — strict TS project refs
-pnpm run test                # 4. test (zero new failures)
+cleo done <TASK_ID> --plan   # 4. tests: affected → ci → full (zero new failures)
 git diff --stat HEAD         # 5. verify scope matches intent
 ```
 
+Step 4 never means a manual full suite. Before merge record
+`tool:test-affected` when `testing.affectedCommand` is configured, else
+`test-run:<json>` from the changed test files; after merge, when the
+project sets `evidence.ciSatisfies`, record `ci:<pr>`. While iterating,
+run only the failing or changed test files.
+
 Note: `pnpm run build` (esbuild) does NOT run the strict TS project-reference
 typecheck. Always run `pnpm run typecheck` separately before tagging or
 marking complete. This was learned the hard way via L-3 in

package/skills/manifest.json

@@ -226,7 +226,7 @@
     },
     {
       "name": "ct-cleo",
-      "version": "2.24.3",
+      "version": "2.24.4",
       "description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
       "path": "skills/ct-cleo",
       "tier": 0,
@@ -885,7 +885,7 @@
     },
     {
       "name": "ct-ivt-looper",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "description": "Runs a project-agnostic autonomous Implement-then-Validate-then-Test compliance loop on any git worktree. Detects the project's test framework (vitest, jest, mocha, pytest, unittest, go-test, cargo-test, rspec, phpunit, bats, or other) and iterates until the implementation satisfies its specification, recording convergence metrics to the manifest. Use when given an implementation task that must ship verified: the IVT loop is the autonomous compliance layer enforced before any release or PR. Triggers on phrases like 'implement and verify', 'run the IVT loop', 'ship this task', 'complete implementation with tests', 'verify against spec', or any implementation task with acceptance criteria. Works in any git worktree regardless of language or framework, never hardcoded to one project's tooling.",
       "path": "skills/ct-ivt-looper",
       "tier": 1,
@@ -983,7 +983,7 @@
     },
     {
       "name": "ct-orchestrator",
-      "version": "4.0.7",
+      "version": "4.0.8",
       "description": "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \\\"orchestrate\\\", \\\"orchestrator mode\\\", \\\"run as orchestrator\\\", \\\"delegate to subagents\\\", \\\"coordinate agents\\\", \\\"spawn subagents\\\", \\\"multi-agent workflow\\\", \\\"context-protected workflow\\\", \\\"agent farm\\\", \\\"HITL orchestration\\\", \\\"pipeline management\\\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime.",
       "path": "skills/ct-orchestrator",
       "tier": 0,
@@ -1472,7 +1472,7 @@
     },
     {
       "name": "ct-task-executor",
-      "version": "2.7.6",
+      "version": "2.7.7",
       "description": "General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.",
       "path": "skills/ct-task-executor",
       "tier": 0,