@cleocode/skills 2026.10.27 → 2026.11.1-canary.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cleocode/skills",
3
- "version": "2026.10.27",
3
+ "version": "2026.11.1-canary.2",
4
4
  "description": "CLEO skill definitions - bundled with CLEO monorepo",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",
@@ -2,14 +2,14 @@
2
2
  name: ct-cleo
3
3
  description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
4
4
  metadata:
5
- version: 2.24.24
5
+ version: 2.25.1
6
6
  tier: core
7
7
  install: harness
8
8
  covers:
9
9
  - packages/cleo/src/cli/commands/session.ts
10
10
  - packages/cleo/src/cli/commands/focus.ts
11
11
  - packages/cleo/src/cli/commands/sticky.ts
12
- lastReviewed: 2026-10-25
12
+ lastReviewed: 2026-10-28
13
13
  stability: stable
14
14
  ---
15
15
 
@@ -152,7 +152,7 @@ Unattributed mutations warn on stderr; `session status` / `briefing` label a gue
152
152
  | End session (from another terminal) | `cleo session end --session <id>` |
153
153
  | Find work | `cleo next` → `cleo focus <id>` |
154
154
  | Search tasks | `cleo find "query"` |
155
- | Complete task | `cleo verify T### --gate ... --evidence "..."` → `cleo complete T###` |
155
+ | Complete task | PR: `Closes: T### AC1,AC2` in the body, merge on green; the sweep closes it. No PR: `cleo done T### --plan` → `cleo verify …` → `cleo complete T###` |
156
156
  | Run typed gates (the only command that executes them; writes read the cache) | `cleo verify T### --run [--req A,B]` |
157
157
  | Save memory | `cleo memory observe "..." --title "..."` |
158
158
  | Spawn subagent | `cleo orchestrate spawn <taskId> --tier 2` |
@@ -463,4 +463,4 @@ BRAIN ID going forward.
463
463
 
464
464
  ## Evidence must prove task criteria
465
465
 
466
- 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`; after merge a scoped run carries only while the change's files are byte-identical, or when it is a `test-run:` recorded on a main HEAD descending from the merge, on the current tree, covering the change (T13673); plan with `cleo done <id> --plan`, which never plans a whole-suite `tool:test` itself (T13647); never run the suite by hand and again via `tool:test`). Run tests, typechecks and builds one at a time through `cleo run --wait --class <test|build|full-build> -- <cmd>` (exit 75: not admitted yet, wait and retry); never wrap `cleo run` or `cleo verify` in another queue or wrapper, and never raise heap or worker counts (`NODE_OPTIONS`, `--maxWorkers`). 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.
466
+ A merged PR closes its `Closes:` tasks once `CI` is green on its exact head and a non-author reviewer recorded `met` for each AC (`cleo review verdict`); the merge sweep records `pr:`, `ci:` and `satisfies:`, so no agent step follows the merge (ADR-099; preview with `cleo done --from-merge <pr> --dry-run`). No-PR work records its own results: plan with `cleo done <id> --plan` (it never plans a whole-suite `tool:test`, T13647), then the atoms in `cleo briefing inject --section evidence`, each linked with `satisfies:T1234#AC1`. Run tests, typechecks and builds one at a time through `cleo run --wait --class <test|build|full-build> -- <cmd>` (exit 75: not admitted yet, wait and retry); never wrap `cleo run` or `cleo verify` in another queue or wrapper, and never raise heap or worker counts (`NODE_OPTIONS`, `--maxWorkers`). 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.
@@ -34,9 +34,13 @@ gates work only where a project turns on the stage gate (below).
34
34
 
35
35
  ## 3. Verify
36
36
 
37
- - `cleo done <id> --plan`, record each gate with `cleo verify <id> --gate <gate>
38
- --evidence "<atoms>"`, then `cleo complete <id>`.
39
- - Each PR head gets an independent review before merge.
37
+ - PR work: the PR body names each task and its ACs (`Closes: T#### AC1,AC2`, or
38
+ `Refs:` for partial delivery). A non-author reviewer records a verdict per AC
39
+ on the PR head (`cleo review verdict`). Merge on green `CI`; the merge sweep
40
+ closes the task. Check the lines first with
41
+ `cleo done --from-merge <pr> --dry-run`.
42
+ - No-PR work: `cleo done <id> --plan`, record each gate with
43
+ `cleo verify <id> --gate <gate> --evidence "<atoms>"`, then `cleo complete <id>`.
40
44
 
41
45
  ## Spawn protocols are labels
42
46
 
@@ -144,16 +144,14 @@ cleo skills info ct-orchestrator
144
144
 
145
145
  ## Release Workflow
146
146
 
147
- Releases are PR-gated (ADR-065). Commit and merge all code through PRs first; the
148
- release verbs are `plan` → `open` → `reconcile`. The legacy `create`/`ship`
149
- verbs were removed (T9540, T10103).
147
+ A release is one command (ADR-099). Merge all code through PRs first; `cut`
148
+ picks the newest commit on `origin/main` whose `CI` is green, builds the notes
149
+ from the changesets since the last tag, and creates the tag that starts
150
+ `release.yml`. Provenance is reconciled automatically by the merge sweep.
150
151
 
151
152
  ```bash
152
- cleo release plan v2026.MM.N --epic T#### # or --tasks T1,T2
153
- cleo release open v2026.MM.N # dispatches release-prepare
154
- cleo release pr-status v2026.MM.N # poll the release PR + CI
155
- git tag -a v2026.MM.N -m "Release v2026.MM.N" && git push origin v2026.MM.N
156
- cleo release reconcile v2026.MM.N # backfill provenance
153
+ cleo release cut v2026.MM.N --dry-run # sha, CI run, notes, packages, task report
154
+ cleo release cut v2026.MM.N # tag and publish
157
155
  ```
158
156
 
159
157
  ## Project Context
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ct-dev-workflow
3
3
  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.
4
- version: 3.1.31
4
+ version: 3.4.0
5
5
  protocol: contribution
6
6
  dependencies: []
7
7
  sharedResources:
@@ -14,7 +14,7 @@ compatibility:
14
14
  - gemini-cli
15
15
  license: MIT
16
16
  metadata:
17
- version: 3.1.31
17
+ version: 3.4.0
18
18
  tier: core
19
19
  install: harness
20
20
  covers:
@@ -26,16 +26,15 @@ metadata:
26
26
  - packages/core/src/hooks.ts
27
27
  - packages/core/templates/git-hooks/**
28
28
  - packages/contracts/src/git-hooks.ts
29
- lastReviewed: 2026-10-24
29
+ lastReviewed: 2026-10-29
30
30
  stability: stable
31
31
  ---
32
32
 
33
33
  # Development Workflow Context Injection
34
34
 
35
35
  Opt-in unified-hook releases use the numbered `vYYYY.MM.N-canary.N` channel
36
- through the normal release plan/open and OIDC workflow. The release-preparation
37
- workflow accepts this channel explicitly; publication stays on `canary` and does
38
- not advance to `latest`. Preserve registry retries and installed-package soak
36
+ through `cleo release cut` and the OIDC workflow. The version suffix picks the npm
37
+ dist-tag, so publication stays on `canary` and does not advance to `latest`. Preserve registry retries and installed-package soak
39
38
  checks. Stable promotion needs the separately retained, source-bound live harness
40
39
  and hosted VidaPeps pilot evidence; missing or unavailable verification holds it.
41
40
  The stable target may follow the canary base when npm has already advanced, but
@@ -303,70 +302,38 @@ git push origin HEAD
303
302
  # - Installation test
304
303
  ```
305
304
 
306
- ### G5: Version Bump (Release Only)
305
+ ### G5: Pull request
307
306
 
308
- **Only for releases**, not every commit.
307
+ Every change reaches main through a PR. The body names each task and the ACs the
308
+ PR delivers, one line per task (ADR-099):
309
309
 
310
- ```bash
311
- # 1. Preview
312
- ./dev/bump-version.sh --dry-run patch
313
-
314
- # 2. Execute
315
- ./dev/bump-version.sh patch
316
-
317
- # 3. Validate
318
- ./dev/validate-version.sh
319
-
320
- # 4. Reinstall locally
321
- ./install.sh --force
322
- cleo version
310
+ ```
311
+ Closes: T1456 AC1,AC2
312
+ Refs: T1400 AC3
323
313
  ```
324
314
 
325
- ### G6: Tag & Release
326
-
327
- **GitHub Actions handles release creation.**
315
+ `Closes:` completes the task once its ACs are covered; `Refs:` binds ACs for
316
+ partial delivery. The PR text never waives an AC. Check the lines against the
317
+ store before merge:
328
318
 
329
319
  ```bash
330
- # 1. Create annotated tag
331
- git tag -a v${VERSION} -m "${TYPE}: ${SUMMARY}"
320
+ cleo done --from-merge <pr> --dry-run
321
+ ```
332
322
 
333
- # 2. Push tag (triggers release workflow)
334
- git push origin v${VERSION}
323
+ A reviewer that is not the author records a verdict per AC on the PR head
324
+ (`cleo review packet <pr> --task T1456`, then `cleo review verdict`). Merge on
325
+ green `CI`; the merge sweep closes the task and records its evidence. No step
326
+ follows the merge.
335
327
 
336
- # 3. Push branch
337
- git push origin HEAD
328
+ ### G6: Release
338
329
 
339
- # GitHub Actions automatically:
340
- # - Builds release tarball
341
- # - Creates GitHub Release
342
- # - Generates release notes
343
- # - Uploads artifacts
344
- ```
330
+ Commits never bump versions or tag. Each user-facing change carries a
331
+ `.changeset/` entry, and a release is one command run by the lead:
345
332
 
346
- **Release preflight (`release-prepare.yml`).** `cleo release open <version>`
347
- checks main's HEAD SHA and dispatches with `skip-tests=true` when the `ci.yml`
348
- push run for that SHA, or for an ancestor reached only through release-plan
349
- commits (the plan file, changesets, CHANGELOG; T13140), is green AND ran every
350
- Linux `Unit Tests` shard green (a docs-only push that skipped the tests does
351
- not count). It sets `skip-macos-tests=true` when the newest completed nightly
352
- or `macos-main.yml` (main-push, never cancelled mid-run, pending pushes coalesce;
353
- T13143, T13187) run with macOS jobs for
354
- one of those commits is green. A `ci.yml` push run still queued or in progress
355
- is polled for up to 10 minutes first (T13823). The SHA travels as
356
- `verified-sha` and the proving run's id as `reused-ci-run`; the workflow
357
- ignores the skips if it checks out another commit or `verified-sha` is empty,
358
- and re-reads the reused run from the API (push to main, success, every Linux
359
- shard green, same tree: the exact commit, or one it extends only by
360
- whole-path-allowlisted plan, changeset `.md` and CHANGELOG.md files; T13825)
361
- before it skips the Linux shards, naming the run in the
362
- summary and the bump-PR body. Otherwise the 8 Linux and 8 macOS test shards run, and the reason names
363
- the newest main commit that has a green macOS run. The decision is in the run
364
- summary.
365
-
366
- **Bump-PR merge.** Its `pull_request` runs stay `action_required` (no GitHub
367
- App), so the orchestrator admin-merges once the dispatched `CI` run on the PR
368
- head SHA is green: `gh pr merge <n> --admin --merge` — see
369
- `docs/release/merge-queue-runbook.md`.
333
+ ```bash
334
+ cleo release cut v2026.MM.N --dry-run # green sha, notes, packages, task report
335
+ cleo release cut v2026.MM.N # tags; release.yml builds and publishes
336
+ ```
370
337
 
371
338
  ---
372
339
 
@@ -385,16 +352,27 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
385
352
 
386
353
  ### Do I Need a Version Bump?
387
354
 
388
- | Change | Bump | Tag |
389
- |--------|------|-----|
390
- | `feat` | minor | Yes |
391
- | `fix` | patch | Yes |
392
- | `docs` | No | No |
393
- | `refactor` | patch | Yes |
394
- | `test` | No | No |
395
- | `chore` | No | No |
396
- | `perf` | patch | Yes |
397
- | `security` | patch | Yes |
355
+ No. Add a `.changeset/` entry for user-facing changes; versions and tags come
356
+ from `cleo release cut`.
357
+
358
+ ---
359
+
360
+ ## PR Cadence (D11212)
361
+
362
+ Many small PRs, each tied to a task group, so every change is traceable from
363
+ task to PR to release (spec: `cleo docs fetch pr-cadence`):
364
+
365
+ - **One PR per task group.** A PR delivers one task, or a few tasks that cannot
366
+ land apart. Never bundle unrelated tasks to save a CI run.
367
+ - **Small.** Reviewable in one sitting. Split a large task into PRs that each
368
+ keep `main` green: `Refs:` on each, `Closes:` on the last.
369
+ - **Name the tasks.** One body line per task: `Closes: T#### AC1,AC2` or
370
+ `Refs: T#### AC3`. The `PR Task Lines` check flags a PR with none or with a
371
+ malformed line. A change no task owns takes the `no-task` label.
372
+ - **Changeset** with the same `tasks:` for user-facing changes; release notes
373
+ are built from them.
374
+ - **Batch at release time, not in PRs.** PRs merge one at a time on green
375
+ `CI`; `cleo release cut` ships everything merged since the last tag.
398
376
 
399
377
  ---
400
378
 
@@ -408,7 +386,7 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
408
386
  # Task lifecycle
409
387
  cleo current # Current task
410
388
  cleo start T123 # Start task (on E_SESSION_UNBOUND: bind a session, see above)
411
- cleo complete T123 # Mark done
389
+ cleo complete T123 # Mark done (no-PR work; PR work closes on merge)
412
390
 
413
391
  # Find existing work
414
392
  cleo find "query" # Search tasks
@@ -464,11 +442,12 @@ Co-Authored-By: Claude <noreply@anthropic.com>
464
442
  EOF
465
443
  )"
466
444
 
467
- # 6. Push (CI handles full tests)
445
+ # 6. Push and open a PR whose body says `Closes: T1456 AC1,AC2`
468
446
  git push origin HEAD
447
+ gh pr create --fill
448
+ cleo done --from-merge <pr> --dry-run
469
449
 
470
- # 7. Mark task complete
471
- cleo complete T1456
450
+ # 7. Merge on green CI after the per-AC review; the merge sweep closes T1456
472
451
  ```
473
452
 
474
453
  ### Example 2: Documentation Only
@@ -492,11 +471,11 @@ Co-Authored-By: Claude <noreply@anthropic.com>
492
471
  EOF
493
472
  )"
494
473
 
495
- # 5. Push
474
+ # 5. Push and open a PR whose body says `Closes: T1550 AC1`
496
475
  git push origin HEAD
476
+ gh pr create --fill
497
477
 
498
- # 6. Complete
499
- cleo complete T1550
478
+ # 6. Merge on green CI after the per-AC review; the merge sweep closes T1550
500
479
  ```
501
480
 
502
481
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ct-documentor
3
3
  description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.
4
- version: 3.27.0
4
+ version: 3.33.0
5
5
  protocol: null
6
6
  dependencies:
7
7
  - ct-spec-writer
@@ -16,13 +16,13 @@ compatibility:
16
16
  - gemini-cli
17
17
  license: MIT
18
18
  metadata:
19
- version: 3.27.0
19
+ version: 3.33.0
20
20
  tier: core
21
21
  install: harness
22
22
  covers:
23
23
  - packages/cleo/src/cli/commands/docs.ts
24
24
  - packages/contracts/src/docs-taxonomy.ts
25
- lastReviewed: 2026-10-27
25
+ lastReviewed: 2026-10-28
26
26
  stability: stable
27
27
  ---
28
28
 
@@ -64,11 +64,30 @@ ratio from the docs audit log, loose-markdown count (gitignore-aware scan),
64
64
  `docs_wikilinks` edge count, and live `decision_adr_links` count. Use it for
65
65
  pilot baseline comparisons — it never writes.
66
66
 
67
+ `cleo docs rot` (T14111) is the docs-rot check every cycle runs. A doc declares
68
+ the code it documents in frontmatter, `covers:` with repo globs (the skill
69
+ `metadata.covers` grammar); write it into the store doc and republish, never
70
+ the mirror alone. The report reads git only: **stale** (covered code changed on
71
+ main after the doc did), **duplicates** (same body, near-identical titles),
72
+ **orphans** (a covers glob matching nothing, a `docs/` file nothing names).
73
+ `--changed <base>..<head>` lists the docs a merged change left stale (the
74
+ post-merge sweep labels its tasks `docs-update`); `--strict` exits 2 on any
75
+ finding, and the release cut runs it. When you change covered code, update the
76
+ doc in the same PR.
77
+
67
78
  `cleo docs doctor` (T13447) audits the docs store — dangling `local-file`
68
79
  pointers, docVersion skew vs the audit log, empty topics/related_tasks,
69
- `docs_wikilinks` drift, legacy store surfaces, stale drafts — and with
70
- `--apply` repairs them after creating a backup automatically. Use it for
71
- store hygiene checks; it never edits doc content.
80
+ `docs_wikilinks` drift, legacy store surfaces, stale drafts, and
81
+ `docs_publications` ledger rows whose mirror is gone (including dead worktree
82
+ paths) or stale (T14117) — and with `--apply` repairs them after creating a
83
+ backup automatically. The ledger syncs across devices, so a row is pruned
84
+ only when its mirror is provably gone (absent from HEAD and the default
85
+ branch, or in a removed worktree of this device) and its blob stays
86
+ referenced elsewhere; absolute paths and other devices' paths are only
87
+ reported. Each pruned row is first appended to
88
+ `.cleo/audit/docs-publications-prune.jsonl`, and stale mirrors are only
89
+ reported (republish, or ingest the edit with `cleo docs update`). Use it for store
90
+ hygiene checks; it never edits doc content.
72
91
 
73
92
  `cleo docs migrate` (T13360) imports legacy docs + history into the re-keyed
74
93
  conduit store inside the migration safety harness (pre-step backup, verified
@@ -155,6 +174,14 @@ materializing through `cleo docs add` + (optionally) `cleo docs publish`.
155
174
 
156
175
  ---
157
176
 
177
+ ## Kinds and names (T14107 · D11210)
178
+
179
+ One kind per published directory; `cleo docs list-types` prints them (adr, spec, plan, research, guide, concept, reference, migration, release-note, note; handoffs are store-only and never published). Name a doc by its subject: lowercase kebab-case, at most 64 characters, with no task id, session id or date in it. The ADR number and the release-note version are allowed. Task and decision links and dates go in the doc's metadata. `cleo docs add` refuses a new slug that breaks the rule with `E_DOC_NAME_RULE` and a subject-only suggestion (existing docs keep their names and still read, update and fetch), CLEO's own minted slugs (ADR allocation, the spawn `{{TOPIC_SLUG}}`) follow it, and `cleo check canon docs` refuses a tracked doc whose name breaks the rule, naming the `git mv` that fixes it; the rule is implemented once in `packages/core/src/docs/doc-name-rule.ts` (`docNameViolation`), and names that broke it before it existed are in the shrink-only `scripts/.docs-name-baseline.json`.
180
+
181
+ ## Update before create (T14109 · D11210)
182
+
183
+ Before adding a doc, find the one that already covers the subject and update it. `cleo docs add` refuses a likely duplicate with `E_DOC_DUPLICATE`: same content, a similar slug of the same kind, a similar title, or text that mostly repeats an existing doc. The refusal names the existing doc's slug and title and the commands to read it (`cleo docs fetch <slug>`) and update it (`cleo docs update <slug>`). Add a new doc anyway only when it really is different, with `--new-because "<why it is not the existing doc>"`; the reason is recorded in `.cleo/audit/docs-new-because.jsonl`. `--allow-similar` alone no longer bypasses the check.
184
+
158
185
  ## Decision: update vs supersede vs create (T10168 · Saga T9855 / E12)
159
186
 
160
187
  Before adding a new doc, ALWAYS ask: is this **a new doc**, **a change to an existing doc**, or **a replacement for an existing doc**? Prefer the canonical six-verb path (`add` / `update` / `fetch` / `list` / `remove` / `publish`). Legacy verbs annotated below.
@@ -785,6 +812,25 @@ BEFORE creating ANY new file, you MUST:
785
812
  4. Only create new files when NO suitable location exists
786
813
  ```
787
814
 
815
+ ### Modernize a messy docs folder (T14113)
816
+
817
+ To clean up a whole tree (task- or date-named files, duplicates, split
818
+ category folders), use `cleo docs modernize` instead of moving files by hand:
819
+
820
+ ```bash
821
+ cleo docs modernize docs --out plan.json # dry run: kind, slug, keep/rename/merge-into/delete + reasons
822
+ cleo docs modernize --apply --plan plan.json # apply the reviewed plan; prints a receipt runId
823
+ cleo docs modernize --rollback dm-20261028-150000-abc123 # reverse that run
824
+ cleo docs modernize --store # stored docs: re-kind, re-slug (old slug stays an alias), renumber colliding ADRs
825
+ ```
826
+
827
+ Ambiguous classify and merge calls are judged by System One
828
+ (`docs.modernize.classify`, `docs.modernize.merge`; rule fallback when it is
829
+ unreachable) and recorded on each plan row. Apply stores survivors, folds
830
+ duplicates in, supersedes the removed docs, rewrites relative links to
831
+ `[[slug]]` wikilinks (recorded as `links-to` graph edges) and keeps every
832
+ replaced byte under `.cleo/modernize/<runId>/` for rollback.
833
+
788
834
  ---
789
835
 
790
836
  ## Workflow Phases
@@ -2,13 +2,13 @@
2
2
  name: ct-orchestrator
3
3
  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."
4
4
  metadata:
5
- version: 4.1.6
5
+ version: 4.2.0
6
6
  tier: core
7
7
  install: harness
8
8
  covers:
9
9
  - packages/cleo/src/cli/commands/orchestrate.ts
10
10
  - packages/core/src/orchestration/spawn-prompt.ts
11
- lastReviewed: 2026-10-27
11
+ lastReviewed: 2026-10-28
12
12
  stability: stable
13
13
  ---
14
14
 
@@ -117,10 +117,13 @@ the stage gate (see Plan).
117
117
 
118
118
  ### Verify
119
119
 
120
- - Evidence gates (ADR-051): `cleo done <id> --plan`, then `cleo verify` per gate, then
121
- `cleo complete`. A worker that fails its criteria is re-spawned with the feedback.
122
- - An independent review of each PR head before merge; the implementer never reviews
123
- its own work.
120
+ - PR work (ADR-099): the worker's PR body names each task and its ACs
121
+ (`Closes: T#### AC1,AC2`, or `Refs:` for partial delivery). A reviewer agent that is
122
+ not the author reviews the PR head from `cleo review packet <pr> --task <id>` and
123
+ records `cleo review verdict` per AC; the implementer never reviews its own work.
124
+ Merge on green `CI`; the merge sweep closes the task. A worker that fails its
125
+ criteria is re-spawned with the feedback.
126
+ - No-PR work: `cleo done <id> --plan`, then `cleo verify` per gate, then `cleo complete`.
124
127
 
125
128
  ### Contribution (cross-cutting)
126
129
 
@@ -349,38 +352,30 @@ When operating without continuous HITL oversight, additional constraints apply:
349
352
  | `cleo show T1234` | Full task details |
350
353
  | `cleo add "Task" --parent T1575` | Create child task |
351
354
  | `cleo start T1586` / `cleo complete T1586` | Task lifecycle |
352
- | `cleo verify T1586 --gate <g> --evidence <atoms>` | Evidence-based gate write (ADR-051) |
355
+ | `cleo verify T1586 --gate <g> --evidence <atoms>` | Evidence-based gate write, no-PR work (ADR-051) |
356
+ | `cleo review packet <pr> --task T1586` | Diff and AC text for a non-author reviewer (ADR-099) |
357
+ | `cleo done --from-merge <pr> --dry-run` | Check a PR's `Closes:`/`Refs:` lines before merge |
358
+ | `cleo release cut v2026.MM.N --dry-run` | Preview a release; drop `--dry-run` to tag and publish |
353
359
  | `cleo manifest list --filter pending` | Followup items |
354
360
  | `cleo session end --note "summary"` | End session with handoff context |
355
361
 
356
362
  ## Evidence-Based Completion (ADR-051 / T832)
357
363
 
358
- As of v2026.4.78, every `cleo verify` gate write requires programmatic evidence.
359
- `--all` without `--evidence` is REJECTED. `--force` has been REMOVED from
360
- `cleo complete`. Gates are re-validated at complete time — tampering with
361
- files between `verify` and `complete` triggers `E_EVIDENCE_STALE`.
364
+ PR work closes through the merge sweep (Verify, above): it records `pr:`, `ci:`
365
+ and the `satisfies:` links the reviewer's `met` verdicts bind, so no step follows
366
+ the merge (ADR-099). The rest of this section is for no-PR work, typed gates no CI
367
+ job runs, and PRs merged before the sweep shipped.
362
368
 
363
- ### Evidence per gate (minimum)
364
-
365
- | Gate | Required atoms |
366
- |------|---------------|
367
- | `implemented` | `commit:<sha>` AND `files:<comma-separated>` |
368
- | `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` |
369
- | `qaPassed` | `ci:<pr>` under the same two conditions; else `tool:biome` AND `tool:tsc` (OR `tool:pnpm-build`) |
370
- | `documented` | `files:<docs-path>` OR `url:<doc-url>` |
371
- | `securityPassed` | `tool:security-scan` OR `note:<waiver>` |
372
- | `cleanupDone` | `note:<summary>` |
373
-
374
- Orchestrator workflow for each completing task:
369
+ Every `cleo verify` gate write requires programmatic evidence; `--all` without
370
+ `--evidence` is rejected, and gates are re-validated at complete time (files changed
371
+ between `verify` and `complete` trigger `E_EVIDENCE_STALE`). Atoms per gate:
372
+ `cleo briefing inject --section evidence`.
375
373
 
376
374
  ```bash
377
- # 1. Worker reports done with evidence atoms in manifest key_findings
378
- # 2. Orchestrator plans, then records (cleo done picks affected → ci → full):
379
- cleo done <taskId> --plan
375
+ cleo done <taskId> --plan # names the evidence each gate needs
380
376
  cleo verify <taskId> --gate implemented --evidence "commit:$(git rev-parse HEAD);files:<list>"
381
- cleo verify <taskId> --gate testsPassed --evidence "ci:<pr>" # merged + evidence.ciSatisfies; else tool:test-affected (needs testing.affectedCommand), else tool:test
382
- cleo verify <taskId> --gate qaPassed --evidence "ci:<pr>" # merged + evidence.ciSatisfies; else tool:biome;tool:tsc
383
- # 3. Close:
377
+ cleo verify <taskId> --gate testsPassed --evidence "tool:test-affected" # else test-run:<json> or tool:test
378
+ cleo verify <taskId> --gate qaPassed --evidence "tool:lint;tool:typecheck"
384
379
  cleo complete <taskId>
385
380
  ```
386
381
 
@@ -108,10 +108,11 @@ cleo show T1586
108
108
  # 3. Spawn validation subagent
109
109
  cleo orchestrate spawn T1590 # Validation task
110
110
 
111
- # 4. Set verification gates
112
- cleo verify T1586 --gate testsPassed
113
- cleo verify T1586 --gate qaPassed
114
- cleo verify T1586 --all
111
+ # 4. Record gate evidence (every gate needs programmatic evidence; bare --all is rejected)
112
+ cleo done T1586 --plan # names the atoms each gate needs
113
+ cleo verify T1586 --gate testsPassed --evidence "ci:<pr>" # or tool:test-affected
114
+ cleo verify T1586 --gate qaPassed --evidence "ci:<pr>" # or tool:lint;tool:typecheck
115
+ cleo complete T1586
115
116
 
116
117
  # 5. Parent epic auto-completes when all children verified
117
118
  ```
@@ -120,25 +121,22 @@ cleo verify T1586 --all
120
121
 
121
122
  **Release tasks use the `release` protocol** via `cleo release` commands.
122
123
 
124
+ A release is one command (ADR-099). Every change reaches main through a merged PR
125
+ first; the merge sweep has already closed their tasks.
126
+
123
127
  ```bash
124
- # 1. Verify all epic tasks complete
125
- cleo list --parent T1575 --status pending # Should be empty
126
-
127
- # 2. Run pre-release validation
128
- ./tests/run-all-tests.sh
129
- cleo check arch
130
-
131
- # 3. Plan and open the release PR (ADR-065; merged through PRs, tagged explicitly)
132
- cleo release plan v0.85.0 --tasks T001,T002,T003
133
- cleo release open v0.85.0
134
- cleo release pr-status v0.85.0
135
- git tag -a v0.85.0 -m "Release v0.85.0" && git push origin v0.85.0
136
- cleo release reconcile v0.85.0
128
+ # 1. Check the epic: closing tasks are merged with green CI, sweep pending
129
+ cleo list --parent T1575 --status pending
130
+
131
+ # 2. Preview: the green sha, its CI run, notes, packages, migrations, task report
132
+ cleo release cut v0.85.0 --dry-run
133
+
134
+ # 3. Tag and publish (release.yml builds, publishes and records the verdict)
135
+ cleo release cut v0.85.0
137
136
  ```
138
137
 
139
- **IMPORTANT**: `dev/release-version.sh` is **DEPRECATED** (since v0.78.0), and the
140
- `release create`/`release ship` verbs were removed (T9540, T10103). Always use
141
- `cleo release plan` → `open` → tag → `reconcile`.
138
+ Provenance is reconciled automatically by the merge sweep. The old plan, open and
139
+ pr-status verbs and the hand-pushed tag are retired (T14114).
142
140
 
143
141
  See `src/protocols/release.md` for the full release protocol specification.
144
142
 
@@ -158,7 +156,7 @@ cleo orchestrate spawn T105 # implementation protocol
158
156
  # contribution protocol auto-triggers for shared resources
159
157
 
160
158
  # RELEASE (polish phase)
161
- cleo release plan v0.74.0 --tasks T104,T105
162
- cleo release open v0.74.0
159
+ cleo release cut v0.74.0 --dry-run
160
+ cleo release cut v0.74.0
163
161
  cleo session end --note "Feature X released v0.74.0"
164
162
  ```
@@ -52,7 +52,7 @@ template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
52
52
  |-------|-------------|---------|---------|
53
53
  | `{{TASK_ID}}` | CLEO task identifier | `^T[0-9]+$` | `T1234` |
54
54
  | `{{DATE}}` | ISO date | `YYYY-MM-DD` | `2026-01-20` |
55
- | `{{TOPIC_SLUG}}` | URL-safe topic name | `[a-zA-Z0-9_-]+` | `auth-research` |
55
+ | `{{TOPIC_SLUG}}` | The task's subject in kebab-case: no task id, session id or date (the doc naming rule, T14129) | `[a-zA-Z0-9_-]+` | `auth-research` |
56
56
 
57
57
  ### Task Command Tokens (CLEO defaults)
58
58
 
@@ -1,21 +1,23 @@
1
1
  ---
2
2
  name: ct-release-orchestrator
3
- 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."
3
+ description: "Orchestrates CLEO releases. Default (T14102): cleo release cut {version} tags the newest main commit with green CI, and release.yml writes the CHANGELOG from changesets, publishes, and opens an auto-merging CHANGELOG + version PR; cleo release reconcile records provenance. The SPEC-T9345 4-verb pipeline (cleo release plan, cleo release open, PR + tag) stays one release as a fallback (T14114). 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."
4
4
  protocol: release
5
5
  adrRefs:
6
6
  - ADR-053
7
7
  - ADR-063
8
8
  - ADR-065
9
9
  metadata:
10
- version: 3.2.7
10
+ version: 3.5.0
11
11
  tier: on-demand
12
12
  install: harness
13
13
  covers:
14
14
  - packages/core/src/validation/protocols/cant/release.cant
15
15
  - packages/core/src/validation/protocols/protocols-markdown/release.md
16
16
  - packages/cleo/src/cli/commands/release.ts
17
+ - packages/core/src/release/cut.ts
18
+ - packages/core/src/release/authorization.ts
17
19
  loomStage: release
18
- lastReviewed: 2026-10-16
20
+ lastReviewed: 2026-11-01
19
21
  stability: stable
20
22
  ---
21
23
 
@@ -53,6 +55,34 @@ Owns the canonical 4-verb release pipeline established by SPEC-T9345 and finalis
53
55
 
54
56
  **Single release PR (T13825, owner choice 2026-10-16).** `node scripts/release-run.mjs <ver> --epic <id> --notes-review <file> [--execute]` runs plan → independent notes review (`{"reviewer","notesSha256","approved":true}` by someone other than the operator, for the plan's exact `meta.releaseNotes`) → `release/plan-<ver>` (one commit, plan + CHANGELOG.md, on the default branch's HEAD, made through the GitHub API) → `cleo release open <ver> --ref release/plan-<ver>` → waits for release-prepare and the bump PR's dispatched `CI` on its exact head → version-only assert against the merge-base → `gh pr merge --admin --merge --match-head-commit` plus the `.cleo/audit/force-bypass.jsonl` line → explicit `git tag -a` on the merge commit and push. The bump PR carries the plan and the bump. Dry-run by default; every step resumes on re-run. `--ref` alone dispatches on any plan branch; preflight skips carry over only when it adds release-plan files alone.
55
57
 
58
+ ## One-command release (default, T14102)
59
+
60
+ ```bash
61
+ cleo release cut v2026.10.28 --lead lead.md # report: commit, notes, packages, migrations, task status, confirm command
62
+ cleo release cut v2026.10.28 --sha <sha> --lead lead.md --yes # the printed confirm command: tags that commit
63
+ ```
64
+
65
+ **Confirmation (D11212).** Nothing is tagged without `--yes`; without it the cut reports and prints the exact confirm command, pinned to the previewed sha. With `--yes`, an active standing release authorization covering the version, or the `release.agentCut` setting, allows the tag (an agent); otherwise the cut asks on the controlling terminal (`/dev/tty`) and tags only when the version is typed exactly, refusing with `E_RELEASE_NOT_AUTHORIZED` (and naming the scope to grant) when there is no terminal. The typed confirmation stops casual misuse only: a caller that drives a pseudo-terminal can still type the version. The audit row records `allowedBy` (`tty-confirm`, `authorization:<id>` or `setting:release.agentCut=<level>@<scope>`).
66
+
67
+ **Agent cut setting (T14170, D11221).** `release.agentCut` is `off` (default), `canary`, `prerelease` or `stable`; an agent sets it with `cleo config set release.agentCut canary --scope global`, with no terminal or owner password. Each level covers its own scope and every narrower one: `canary` covers `-canary.N`, `prerelease` any prerelease, `stable` everything. A project value (even `off`) shadows the global one. A cut it allows reports `allowedBy`, a warning naming the setting, and an audit row with `scope` and `settingSource`; when it does not cover the version and there is no terminal, the refusal names the exact `cleo config set` command.
68
+
69
+ **Standing authorization (T14141, D11215).** The owner grants it at a terminal with the owner-auth password: `cleo release authorize --scope canary|prerelease|stable|<version> --expires 7d --reason "<why>" [--uses <n>]` (at most 30d; no use limit unless `--uses`). It is signed with the enrolled owner key (`cleo config owner-enroll`), stored in `.cleo/release-authorizations.json` and the global store, recorded as an owner decision, and audited in `.cleo/audit/release-authorizations.jsonl`. `cleo release authorize --list` shows each grant's state; `--revoke <id>` (owner password too) ends one now with a signed revocation, and the revocation count is sealed in `.cleo/owner-settings.json` (commit it). An edited, unsigned or one-sided grant is ignored; an edited, unsigned or shortened revocation list makes every grant tampered (fail closed). `cleo doctor` reports both. A cut it allows carries `Authorized-by: <id>` in the tag message.
70
+
71
+ - **Commit:** the newest first-parent commit of `origin/main` whose `CI` check run concluded `success`; `--sha` pins one, which must itself be green. Nothing reruns the test suites: CI already passed that tree.
72
+ - **Notes:** the changesets added since the previous release tag, led by `--lead` (stored as the tag annotation). A changeset no merged PR brought in is refused (`E_RELEASE_UNMERGED_CHANGESET`); no green commit is `E_RELEASE_NO_GREEN_COMMIT`.
73
+ - **Docs rot (T14111):** the dry run shows `cleo docs rot` findings; a real stable cut refuses with `E_DOCS_ROT` before tagging while any stale, duplicate or orphaned doc remains; on a prerelease (canary) it is a warning only.
74
+ - **Provenance:** the merge sweep reconciles the newest stable tag automatically once its GitHub release exists (ADR-099); there is no manual reconcile step.
75
+ - **Cleanup (T14142):** the report shows the plan for the release tasks' worktrees and `task/*` branches, plus nested repository copies proven redundant (clean, every ref on origin) only inside the worktrees of the release's done or cancelled tasks; a confirmed cut applies it after the tag. A cleanup failure never fails the cut, and changesets naming no task skip it.
76
+ - **Which checkout (T14160):** `cut` runs every git and gh call, the docs-rot scan and `checkoutAtMain` in the checkout it is started from (a CLEO worktree, or the project root); it never runs git in another checkout. From a worktree the merge sweep and the cleanup, which work on the project checkout, are skipped and named in the report.
77
+ - **Task status is reported, never gated.** Green CI on the sha is the gate; a pending task does not block the cut.
78
+ - **Tag:** an annotated `v<ver>` made through the GitHub API with your `gh` token, which starts `release.yml`. It runs `cleo release write-changelog`, publishes, and on a stable release opens `release/v<ver>`, a CHANGELOG + version PR that auto-merges on green and never blocks the release.
79
+
80
+ **Gates (all re-checked):** the version is CalVer for this month, above every release tag and main's `package.json`; the commit is first-parent on `origin/main` with every `release.prRequiredWorkflows` check (app-pinned, push run) green; the local checkout is at `origin/main`; CI is judged again right before the tag; every real cut writes a row to `.cleo/audit/release-cut.jsonl`. `release.yml` runs `cleo release verify-tag` before publishing, so a hand-pushed or dispatched tag on an untested tree never ships.
81
+
82
+ **Rollback.** A bad tag before `release.yml` publishes: cancel the run (`gh run cancel <id>`) and delete the tag (`git push origin :refs/tags/v<ver>`), then cut again. After publish, fix forward with the next version. If `changelog-pr` fails after a publish, re-run that job, or open the PR by hand from main: `cleo release write-changelog <ver> --ref v<ver>` plus `node scripts/version-all.mjs --set <ver>`.
83
+
84
+ The plan/open pipeline below stays for one release as a fallback; T14114 deletes it.
85
+
56
86
  ## Canonical Pipeline
57
87
 
58
88
  | Step | Verb / Workflow | Owns transition | Notes |
@@ -79,10 +109,10 @@ Optional validators (read-only / dry-run):
79
109
  | RLSE-001 | Version MUST be CalVer (`YYYY.MM.patch`) per ADR-065 — never SemVer. | `cleo release plan` rejects non-CalVer; exit 53. |
80
110
  | RLSE-002 | `CHANGELOG.md` MUST be updated before the tag — always-write is the default behaviour of `cleo release plan` (T9784 deleted the manual changelog verb). | Plan envelope refuses to advance to `pr-opened` if the changeset directory is unparseable (T10105). |
81
111
  | RLSE-003 | All per-task evidence gates MUST be recorded via `cleo verify <task> --gate <g> --evidence …` BEFORE `cleo complete`. The legacy `cleo release verify` batch verb was deleted in T9540. | ADR-051 per-task evidence ritual. | <!-- cleo-cmd: negative-example: release verify -->
82
- | RLSE-004 | The release MUST be tagged explicitly (`git tag -a v<ver>` + `git push origin v<ver>`) after the release PR merges. | Auto-tag was retired in T10434 / ADR-087: `GITHUB_TOKEN` tag pushes did not reliably trigger `release.yml`. |
83
- | RLSE-005 | Direct pushes to `main` are prohibited. Every release ships via a PR cut by `release-prepare.yml`. | ADR-065 + branch protection (see `docs/release/branch-protection-setup.md`). |
112
+ | RLSE-004 | The release MUST be tagged explicitly: by `cleo release cut` (API tag on the green sha), or on the fallback path with `git tag -a v<ver>` + `git push origin v<ver>` after the release PR merges. | Auto-tag was retired in T10434 / ADR-087: `GITHUB_TOKEN` tag pushes did not reliably trigger `release.yml`. |
113
+ | RLSE-005 | Direct pushes to `main` are prohibited. A cut release reaches main's CHANGELOG and versions through `release.yml`'s auto-merging `release/v<ver>` PR; the fallback path through the PR `release-prepare.yml` cuts. | ADR-065 + branch protection (see `docs/release/branch-protection-setup.md`). |
84
114
  | RLSE-006 | Version MUST be consistent across all workspace targets resolved by `resolveVersionBumpTargets` (root package.json + every workspace package + Cargo workspace). | Version-bump preflight in `release-prepare.yml`. |
85
- | RLSE-007 | Provenance reconcile MUST run within the release-publish workflow — never as a manual followup. | Invoked by `release-publish.yml`. |
115
+ | RLSE-007 | Provenance reconcile runs automatically: the merge sweep calls `reconcileLatestRelease` once the GitHub release exists (ADR-099). Run `cleo release reconcile <ver>` only to recover. | T14101 merge sweep. |
86
116
 
87
117
  ## Integration
88
118
 
@@ -101,11 +131,18 @@ cleo release open v2026.6.0 --no-commit-plan
101
131
  # 3. (Optional) Poll PR + CI status while the workflow runs.
102
132
  cleo release pr-status v2026.6.0
103
133
 
104
- # 4. After the release PR merges, tag explicitly (auto-tag is retired).
134
+ # 4. Before the tag, prove macOS on the owner's Mac (T14104): release-prepare
135
+ # runs no macOS shards. Check out the exact commit to tag, then:
136
+ node scripts/release-mac-smoke.mjs
137
+ # Builds it, snapshots the real stores into a sandbox (outside the backup
138
+ # rotation), runs the built CLI in a sandboxed HOME and writes evidence +
139
+ # SHA256SUMS to .cleo/release-smoke/<sha>/. Exit 0 = every command passed.
140
+
141
+ # 5. After the release PR merges, tag explicitly (auto-tag is retired).
105
142
  git tag -a v2026.6.0 -m "Release v2026.6.0"
106
143
  git push origin v2026.6.0
107
144
 
108
- # 5. Reconcile — runs automatically inside release-publish.yml.
145
+ # 6. Reconcile — runs automatically inside release-publish.yml.
109
146
  # Run manually only if backfilling a historical release.
110
147
  cleo release reconcile v2026.6.0
111
148
  ```
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ct-task-executor
3
3
  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.
4
- version: 2.8.8
4
+ version: 2.9.0
5
5
  protocol: implementation
6
6
  adrRefs:
7
7
  - ADR-070
@@ -17,7 +17,7 @@ compatibility:
17
17
  - gemini-cli
18
18
  license: MIT
19
19
  metadata:
20
- version: 2.8.8
20
+ version: 2.9.0
21
21
  tier: core
22
22
  install: harness
23
23
  covers:
@@ -29,7 +29,7 @@ metadata:
29
29
  - packages/core/src/validation/protocols/cant/implementation.cant
30
30
  - packages/core/src/validation/protocols/protocols-markdown/implementation.md
31
31
  loomStage: implementation
32
- lastReviewed: 2026-10-26
32
+ lastReviewed: 2026-10-28
33
33
  stability: stable
34
34
  ---
35
35
 
@@ -103,6 +103,7 @@ Context injection for implementation tasks spawned via cleo-subagent. Provides d
103
103
  3. Execute instructions (see Methodology below)
104
104
  4. Verify deliverables against acceptance criteria
105
105
  5. Record output: `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}}`
106
+ - Update before create (T14109): when a doc on the topic exists, `cleo docs update <slug>` it. `cleo docs add` refuses a likely duplicate with `E_DOC_DUPLICATE` and names the existing doc; pass `--new-because "<why>"` only for a truly new doc.
106
107
  6. Record the manifest entry: `cleo manifest append --task {{TASK_ID}} --type implementation --content "<one-paragraph summary>"`
107
108
  7. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
108
109
  8. Return summary message
@@ -145,9 +146,11 @@ A database or service started for a test run must not outlive it. A `docker run`
145
146
  `cwd`; a locked stage also needs `--reason`. Then verify that gate again.
146
147
  2. **Document completion** - Write detailed output file
147
148
  3. **Update manifest** - Append summary entry
148
- 4. **Complete task** - Mark task done in task system. `cleo done <id> --pr <n>` completes
149
- through PR `<n>`: the plan and the completion judge a scoped test run against the same
150
- merge commit, so a ready plan is not refused by a different carrier.
149
+ 4. **Complete task** - PR work: put `Closes: <id> AC1,AC2` (or `Refs:` for partial
150
+ delivery) in the PR body and check it with `cleo done --from-merge <pr> --dry-run`.
151
+ Once a non-author reviewer records `met` per AC and the PR merges on green `CI`, the
152
+ merge sweep closes the task; no step follows the merge (ADR-099). No-PR work:
153
+ `cleo done <id> --plan`, record what it names, then `cleo complete <id>`.
151
154
  Completion merges the task branch into the local default branch only for a worktree
152
155
  CLEO provisioned, only when the main checkout is already on that branch with no
153
156
  uncommitted tracked changes, and never pushes; a hand-made `task/<id>` branch is
@@ -220,7 +223,7 @@ Record it with `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC
220
223
 
221
224
  ## Acceptance Criteria Verification
222
225
 
223
- Record each criterion's changed artifacts and actual verification results. A merged PR with green CI provides provenance; it cannot automatically satisfy implementation, testing and review. Use `pr:<number>;files:<changed-path>` for implementation (`pr:<component>@<integration>` when your PR merged into an integration branch) and actual result atoms for test/review gates, with explicit `satisfies:T1234#AC1` links for canonical criteria. The PR must relate to the task; documentation-only changes cannot prove a code fix. Research and documentation tasks may use appropriately scoped documentary evidence: they owe `verification.requiredGatesByKind` (default: the required gates without `testsPassed`/`qaPassed`), but once their work touches any non-document path they owe the full code gates, whatever their kind or labels. Fetch the merge commit before claiming its artifact bytes were inspected. Criterion edits require fresh evidence. A completed child does not establish that its parent's independent criteria were met. `cleo verify <id> --all` sets every required gate at once and still requires `--evidence`; bare `--all` is rejected with `E_EVIDENCE_MISSING`. A failing `tool:<name>` reason names the resolved command and its source, so check that command before retrying. To adopt a native typecheck or lint run for `qaPassed` without re-running it, record one `qa-run:<receipt.json>` per check (`cleo verify --help` lists the receipt shape). A change with unit and e2e tests can record both runs in one write, `test-run:<vitest.json>;test-run:<playwright.json>` (Playwright `--reporter=json`): their passing test files cover the change together.
226
+ Record each criterion's changed artifacts and actual verification results. A merged PR closes the tasks its body names (`Closes:`) when `CI` is green on its exact head and an independent reviewer recorded `met` for each AC (`cleo review verdict`); the PR text alone never satisfies an AC (ADR-099). Hand-recorded atoms are for no-PR work: use `pr:<number>;files:<changed-path>` for implementation (`pr:<component>@<integration>` when your PR merged into an integration branch) and actual result atoms for test/review gates, with explicit `satisfies:T1234#AC1` links for canonical criteria. The PR must relate to the task; documentation-only changes cannot prove a code fix. Research and documentation tasks may use appropriately scoped documentary evidence: they owe `verification.requiredGatesByKind` (default: the required gates without `testsPassed`/`qaPassed`), but once their work touches any non-document path they owe the full code gates, whatever their kind or labels. Fetch the merge commit before claiming its artifact bytes were inspected. Criterion edits require fresh evidence. A completed child does not establish that its parent's independent criteria were met. `cleo verify <id> --all` sets every required gate at once and still requires `--evidence`; bare `--all` is rejected with `E_EVIDENCE_MISSING`. A failing `tool:<name>` reason names the resolved command and its source, so check that command before retrying. To adopt a native typecheck or lint run for `qaPassed` without re-running it, record one `qa-run:<receipt.json>` per check (`cleo verify --help` lists the receipt shape). A change with unit and e2e tests can record both runs in one write, `test-run:<vitest.json>;test-run:<playwright.json>` (Playwright `--reporter=json`): their passing test files cover the change together. Rust and Python suites record `test-run:` from a JUnit XML report (cargo nextest, pytest `--junitxml`) or libtest JSON lines (`cargo test -- --format json`).
224
227
 
225
228
 
226
229
  | Criterion | Status | Notes |
@@ -53,7 +53,7 @@ condition."
53
53
  | Count | "with N files", "≥3 entries" | `find -type f | wc -l` |
54
54
  | Length/size | "≥50 lines", "≥10K bytes" | `wc -l`, `wc -c` |
55
55
  | Linkage | "linked from", "referenced in" | `grep -F` |
56
- | 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` |
56
+ | Tests pass | "all tests pass", "no regressions" | PR work: green `CI` on the PR head, recorded as `ci:<pr>` by the merge sweep; no-PR work: `tool:test-affected` (with `testing.affectedCommand`), a targeted `test-run:<json>`, or `tool:test` |
57
57
  | Lint clean | "biome check passes" | `pnpm biome check .` |
58
58
  | Build clean | "compiles", "type-checks" | `pnpm run build && pnpm run typecheck` |
59
59
  | Spec match | "satisfies REQ-NNN" | manual trace + test |
@@ -22,10 +22,10 @@ token spend on the task.
22
22
  1. Start with `cleo done <TASK_ID> --plan`. It picks the cheapest valid
23
23
  evidence (affected, then CI, then full) and shows each tool's cache
24
24
  state.
25
- 2. After the PR merges, when the project sets `evidence.ciSatisfies`,
26
- record `testsPassed` and `qaPassed` with `ci:<pr>`. No local run is
27
- needed.
28
- 3. Otherwise use `tool:test-affected` when `testing.affectedCommand` is
25
+ 2. PR work: green `CI` on the PR head is the run. The merge sweep
26
+ records `ci:<pr>` for `testsPassed` and `qaPassed`; no local run and
27
+ no step after the merge are needed.
28
+ 3. No-PR work: use `tool:test-affected` when `testing.affectedCommand` is
29
29
  configured, else `test-run:<json>` from a targeted run of the test
30
30
  files you changed (or `tool:test`).
31
31
  4. While iterating, run only the failing or changed test files.
@@ -11,6 +11,12 @@ canonical names, and the failure modes most often hit.
11
11
  Every task carries six standard gates. Optional gates may be added per
12
12
  task; the standard set is non-negotiable.
13
13
 
14
+ For PR work the merge sweep records these gates itself when the PR merges:
15
+ `pr:<n>;files:<changed paths>` for `implemented`, `ci:<n>` for `testsPassed`
16
+ and `qaPassed`, each with the `satisfies:` links an independent reviewer's
17
+ `met` verdicts bind (ADR-099). The atoms below are for no-PR work, typed
18
+ gates no CI job runs, and PRs merged before the sweep shipped.
19
+
14
20
  | Gate | Meaning | Evidence kind |
15
21
  |------|---------|---------------|
16
22
  | implemented | Code change exists | `commit:<sha>` + `files:<list>` |
@@ -89,13 +95,47 @@ cache when a cached result is suspect.
89
95
 
90
96
  The merged PR's required CI checks, green on its merge commit (needs
91
97
  `evidence.ciSatisfies: true`). Satisfies `testsPassed` and `qaPassed`
92
- with no local run, so it is the default once the PR has merged.
98
+ with no local run. The merge sweep records it for every PR whose body
99
+ names the task (`Closes:`/`Refs:`); record it by hand only for a PR merged
100
+ before the sweep shipped.
93
101
 
94
102
  ```bash
95
103
  cleo verify T### --gate testsPassed --evidence "ci:1234"
96
104
  cleo verify T### --gate qaPassed --evidence "ci:1234"
97
105
  ```
98
106
 
107
+ ### `deploy:<provider>/<deploymentId>@<sha>|<probe-url>`
108
+
109
+ A probed deployment of `<sha>` (T14083). CLEO GETs the probe URL at verify:
110
+ it must return 2xx and name the deployed SHA in an `X-Commit` or `X-Version`
111
+ header or in the body, and that SHA must contain the task's implemented
112
+ commits. It satisfies only the gates the project lists in
113
+ `evidence.deploySatisfies`: none by default, and never `testsPassed` unless
114
+ listed. A probe naming no SHA is refused; serve the SHA, then verify again.
115
+ The probe URL must not carry the SHA itself (`/health?sha=…` is refused: an
116
+ echoing endpoint would prove nothing).
117
+
118
+ ```bash
119
+ cleo verify T### --gate documented --evidence "deploy:railway/dpl_9f3c@1a2b3c4d|https://api.example.com/health"
120
+ ```
121
+
122
+ ### `ci-run:<runId>`
123
+
124
+ A green run of `.github/workflows/repeat-run.yml` (T14149). This route is for a
125
+ criterion that needs a heavy or repeated run, which you never run locally or
126
+ waive. CLEO checks the run on GitHub and its uploaded report: the workflow,
127
+ dispatched on the default branch, latest attempt green, every one of the N runs
128
+ green, and a commit that contains the task's implemented work. The repeated
129
+ test file must be one the task changed, or one a linked criterion names. It
130
+ links criteria and never satisfies `testsPassed` alone, so record it in the
131
+ same write as the gate's other evidence. Record a `ci-run:` within 90 days of
132
+ the run, the artifact's retention; completion doesn't need the artifact.
133
+
134
+ ```bash
135
+ gh workflow run repeat-run.yml -f test=packages/core/src/x/__tests__/y.test.ts -f runs=50
136
+ cleo verify T### --gate testsPassed --evidence "ci:1234;ci-run:40812345678;satisfies:T####AC2"
137
+ ```
138
+
99
139
  ### `test-run:<json-path>`
100
140
 
101
141
  Path to a vitest JSON output file. Re-validated by hash. Preferred for
@@ -148,6 +188,8 @@ they document, they do not prove. Reserve for `cleanupDone`,
148
188
 
149
189
  The full per-task ritual, in order:
150
190
 
191
+ No-PR work (PR work closes through the merge sweep instead):
192
+
151
193
  ```bash
152
194
  # 1. Implement and verify locally (run only the failing/changed test files)
153
195
  pnpm biome check --write .
@@ -138,11 +138,12 @@ cleo done <TASK_ID> --plan # 4. tests: affected → ci → full (zero new fail
138
138
  git diff --stat HEAD # 5. verify scope matches intent
139
139
  ```
140
140
 
141
- Step 4 never means a manual full suite. Before merge record
142
- `tool:test-affected` when `testing.affectedCommand` is configured, else
143
- `test-run:<json>` from the changed test files; after merge, when the
144
- project sets `evidence.ciSatisfies`, record `ci:<pr>`. While iterating,
145
- run only the failing or changed test files.
141
+ Step 4 never means a manual full suite. PR work needs no local evidence
142
+ run: green `CI` on the PR head is the proof, and the merge sweep records
143
+ `ci:<pr>` (ADR-099). No-PR work records `tool:test-affected` when
144
+ `testing.affectedCommand` is configured, else `test-run:<json>` from the
145
+ changed test files. While iterating, run only the failing or changed test
146
+ files.
146
147
 
147
148
  Note: `pnpm run build` (esbuild) does NOT run the strict TS project-reference
148
149
  typecheck. Always run `pnpm run typecheck` separately before tagging or
@@ -226,7 +226,7 @@
226
226
  },
227
227
  {
228
228
  "name": "ct-cleo",
229
- "version": "2.24.24",
229
+ "version": "2.25.1",
230
230
  "description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
231
231
  "path": "skills/ct-cleo",
232
232
  "tier": 0,
@@ -566,7 +566,7 @@
566
566
  },
567
567
  {
568
568
  "name": "ct-dev-workflow",
569
- "version": "3.1.31",
569
+ "version": "3.4.0",
570
570
  "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.",
571
571
  "path": "skills/ct-dev-workflow",
572
572
  "tier": 0,
@@ -642,7 +642,7 @@
642
642
  },
643
643
  {
644
644
  "name": "ct-documentor",
645
- "version": "3.27.0",
645
+ "version": "3.33.0",
646
646
  "description": "Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.",
647
647
  "path": "skills/ct-documentor",
648
648
  "tier": 0,
@@ -1001,7 +1001,7 @@
1001
1001
  },
1002
1002
  {
1003
1003
  "name": "ct-orchestrator",
1004
- "version": "4.1.6",
1004
+ "version": "4.2.0",
1005
1005
  "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.",
1006
1006
  "path": "skills/ct-orchestrator",
1007
1007
  "tier": 0,
@@ -1167,8 +1167,8 @@
1167
1167
  },
1168
1168
  {
1169
1169
  "name": "ct-release-orchestrator",
1170
- "version": "3.2.7",
1171
- "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.",
1170
+ "version": "3.5.0",
1171
+ "description": "Orchestrates CLEO releases. Default (T14102): cleo release cut {version} tags the newest main commit with green CI, and release.yml writes the CHANGELOG from changesets, publishes, and opens an auto-merging CHANGELOG + version PR; cleo release reconcile records provenance. The SPEC-T9345 4-verb pipeline (cleo release plan, cleo release open, PR + tag) stays one release as a fallback (T14114). 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.",
1172
1172
  "path": "skills/ct-release-orchestrator",
1173
1173
  "tier": 1,
1174
1174
  "deliveryTier": "on-demand",
@@ -1489,7 +1489,7 @@
1489
1489
  },
1490
1490
  {
1491
1491
  "name": "ct-task-executor",
1492
- "version": "2.8.8",
1492
+ "version": "2.9.0",
1493
1493
  "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.",
1494
1494
  "path": "skills/ct-task-executor",
1495
1495
  "tier": 0,