@cleocode/skills 2026.10.27 → 2026.11.1-canary.3

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/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @cleocode/skills
2
2
 
3
+ > Part of [CLEO](https://github.com/kryptobaseddev/cleo#readme). Start with the root README; run `cleo <command> --help` for any command.
4
+
3
5
  CLEO skill definitions - bundled capabilities for AI agents.
4
6
 
5
7
  ## Overview
@@ -61,7 +63,7 @@ installability and every documented `cleo` command honest.
61
63
  | **ct-epic-architect** | Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. |
62
64
  | **ct-ivt-looper** | Runs a project-agnostic autonomous Implement-then-Validate-then-Test compliance loop on any git worktree. |
63
65
  | **ct-provenance-keeper** | Generates in-toto v1 attestations, SLSA-level provenance records, SBOMs (CycloneDX or SPDX), and sigstore/cosi… |
64
- | **ct-release-orchestrator** | Orchestrates the canonical 4-verb release pipeline introduced by SPEC-T9345: cleo release plan, then cleo rele… |
66
+ | **ct-release-orchestrator** | Orchestrates CLEO releases: `cleo release cut <version>` tags the newest main commit with green CI, and release.yml writes the CHANGELOG from changesets and publishes. |
65
67
  | **ct-research-agent** | Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase … |
66
68
  | **ct-spec-writer** | Technical specification writing using RFC 2119 language for clear, unambiguous requirements. |
67
69
  | **ct-validator** | Compliance validation for verifying systems, documents, or code against requirements, schemas, or standards. |
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.3",
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.1
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.1
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-11-02
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
@@ -107,6 +106,12 @@ only on a parentless first commit (T13582); a later commit with that subject, or
107
106
  longer or different subject, still needs a task ID. A template change adds the
108
107
  previously shipped hash to `legacy-hashes.json` so installed copies refresh.
109
108
 
109
+ The managed pre-commit refuses CLEO runtime state staged at ANY path (T14189):
110
+ `cleo.db`/`brain.db`/`tasks.db` and their WAL sidecars by name, a `project-info.json`
111
+ naming a `"projectId"`, and `.cleo/config.json` or a byte-identical copy. It lists the
112
+ paths and `git reset -q -- <paths>`; `cleo doctor` runs the same rule (`staged_cleo_state`).
113
+ This repository's `.githooks/pre-commit` calls the template rather than copying it.
114
+
110
115
  `cleo init` and `cleo upgrade` no longer seed the CleoOS hub (Pi extensions, CANT
111
116
  workflows, justfile) into the global CLEO home (T13994, ADR-098); only the deprecated
112
117
  `cleo admin scaffold-hub` still does.
@@ -303,70 +308,38 @@ git push origin HEAD
303
308
  # - Installation test
304
309
  ```
305
310
 
306
- ### G5: Version Bump (Release Only)
307
-
308
- **Only for releases**, not every commit.
309
-
310
- ```bash
311
- # 1. Preview
312
- ./dev/bump-version.sh --dry-run patch
313
-
314
- # 2. Execute
315
- ./dev/bump-version.sh patch
311
+ ### G5: Pull request
316
312
 
317
- # 3. Validate
318
- ./dev/validate-version.sh
313
+ Every change reaches main through a PR. The body names each task and the ACs the
314
+ PR delivers, one line per task (ADR-099):
319
315
 
320
- # 4. Reinstall locally
321
- ./install.sh --force
322
- cleo version
316
+ ```
317
+ Closes: T1456 AC1,AC2
318
+ Refs: T1400 AC3
323
319
  ```
324
320
 
325
- ### G6: Tag & Release
326
-
327
- **GitHub Actions handles release creation.**
321
+ `Closes:` completes the task once its ACs are covered; `Refs:` binds ACs for
322
+ partial delivery. The PR text never waives an AC. Check the lines against the
323
+ store before merge:
328
324
 
329
325
  ```bash
330
- # 1. Create annotated tag
331
- git tag -a v${VERSION} -m "${TYPE}: ${SUMMARY}"
326
+ cleo done --from-merge <pr> --dry-run
327
+ ```
332
328
 
333
- # 2. Push tag (triggers release workflow)
334
- git push origin v${VERSION}
329
+ A reviewer that is not the author records a verdict per AC on the PR head
330
+ (`cleo review packet <pr> --task T1456`, then `cleo review verdict`). Merge on
331
+ green `CI`; the merge sweep closes the task and records its evidence. No step
332
+ follows the merge.
335
333
 
336
- # 3. Push branch
337
- git push origin HEAD
334
+ ### G6: Release
338
335
 
339
- # GitHub Actions automatically:
340
- # - Builds release tarball
341
- # - Creates GitHub Release
342
- # - Generates release notes
343
- # - Uploads artifacts
344
- ```
336
+ Commits never bump versions or tag. Each user-facing change carries a
337
+ `.changeset/` entry, and a release is one command run by the lead:
345
338
 
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`.
339
+ ```bash
340
+ cleo release cut v2026.MM.N --dry-run # green sha, notes, packages, task report
341
+ cleo release cut v2026.MM.N # tags; release.yml builds and publishes
342
+ ```
370
343
 
371
344
  ---
372
345
 
@@ -385,16 +358,27 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
385
358
 
386
359
  ### Do I Need a Version Bump?
387
360
 
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 |
361
+ No. Add a `.changeset/` entry for user-facing changes; versions and tags come
362
+ from `cleo release cut`.
363
+
364
+ ---
365
+
366
+ ## PR Cadence (D11212)
367
+
368
+ Many small PRs, each tied to a task group, so every change is traceable from
369
+ task to PR to release (spec: `cleo docs fetch pr-cadence`):
370
+
371
+ - **One PR per task group.** A PR delivers one task, or a few tasks that cannot
372
+ land apart. Never bundle unrelated tasks to save a CI run.
373
+ - **Small.** Reviewable in one sitting. Split a large task into PRs that each
374
+ keep `main` green: `Refs:` on each, `Closes:` on the last.
375
+ - **Name the tasks.** One body line per task: `Closes: T#### AC1,AC2` or
376
+ `Refs: T#### AC3`. The `PR Task Lines` check flags a PR with none or with a
377
+ malformed line. A change no task owns takes the `no-task` label.
378
+ - **Changeset** with the same `tasks:` for user-facing changes; release notes
379
+ are built from them.
380
+ - **Batch at release time, not in PRs.** PRs merge one at a time on green
381
+ `CI`; `cleo release cut` ships everything merged since the last tag.
398
382
 
399
383
  ---
400
384
 
@@ -408,7 +392,7 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
408
392
  # Task lifecycle
409
393
  cleo current # Current task
410
394
  cleo start T123 # Start task (on E_SESSION_UNBOUND: bind a session, see above)
411
- cleo complete T123 # Mark done
395
+ cleo complete T123 # Mark done (no-PR work; PR work closes on merge)
412
396
 
413
397
  # Find existing work
414
398
  cleo find "query" # Search tasks
@@ -464,11 +448,12 @@ Co-Authored-By: Claude <noreply@anthropic.com>
464
448
  EOF
465
449
  )"
466
450
 
467
- # 6. Push (CI handles full tests)
451
+ # 6. Push and open a PR whose body says `Closes: T1456 AC1,AC2`
468
452
  git push origin HEAD
453
+ gh pr create --fill
454
+ cleo done --from-merge <pr> --dry-run
469
455
 
470
- # 7. Mark task complete
471
- cleo complete T1456
456
+ # 7. Merge on green CI after the per-AC review; the merge sweep closes T1456
472
457
  ```
473
458
 
474
459
  ### Example 2: Documentation Only
@@ -492,11 +477,11 @@ Co-Authored-By: Claude <noreply@anthropic.com>
492
477
  EOF
493
478
  )"
494
479
 
495
- # 5. Push
480
+ # 5. Push and open a PR whose body says `Closes: T1550 AC1`
496
481
  git push origin HEAD
482
+ gh pr create --fill
497
483
 
498
- # 6. Complete
499
- cleo complete T1550
484
+ # 6. Merge on green CI after the per-AC review; the merge sweep closes T1550
500
485
  ```
501
486
 
502
487
  ---
@@ -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.36.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.36.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-11-02
26
26
  stability: stable
27
27
  ---
28
28
 
@@ -64,11 +64,34 @@ 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. `--apply` runs every repair class
91
+ at once; on a live shared store, scope it with `--only <class,…>` (T14174), for
92
+ example `cleo docs doctor --apply --only publication-ledger-drift`. The dry run's
93
+ `repairCounts` shows planned repairs per class, and an unknown class is refused
94
+ with the valid list.
72
95
 
73
96
  `cleo docs migrate` (T13360) imports legacy docs + history into the re-keyed
74
97
  conduit store inside the migration safety harness (pre-step backup, verified
@@ -155,6 +178,14 @@ materializing through `cleo docs add` + (optionally) `cleo docs publish`.
155
178
 
156
179
  ---
157
180
 
181
+ ## Kinds and names (T14107 · D11210)
182
+
183
+ 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`.
184
+
185
+ ## Update before create (T14109 · D11210)
186
+
187
+ 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.
188
+
158
189
  ## Decision: update vs supersede vs create (T10168 · Saga T9855 / E12)
159
190
 
160
191
  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.
@@ -702,9 +733,14 @@ cleo docs publish --for T1234 --to docs/feature-x.md
702
733
  Atomic tmp-then-rename. The published file ships in the next commit; the
703
734
  SSoT blob remains canonical and continues to track future versions.
704
735
 
705
- `--to` must resolve under the project root (a relative path resolves there)
706
- or inside a registered canonical task worktree; anything else is refused with
707
- `E_VALIDATION_ERROR` and nothing is created. `--dry-run` runs the same checks
736
+ `--to` must resolve under the project root or inside a registered worktree at
737
+ the project's canonical CLEO location (`<cleoHome>/worktrees/<hash>/<name>`,
738
+ any name); anything else is refused with `E_VALIDATION_ERROR` and nothing is
739
+ created. Run from such a worktree, a relative `--to` lands in that worktree, not
740
+ the root checkout, and the publication ledger records the repo-relative path
741
+ the merge makes true (T14135). `cleo docs status` reads a mirror the root
742
+ checkout has not pulled from the default branch, and reports one that sits only
743
+ in an unmerged worktree as `pending-merge`. `--dry-run` runs the same checks
708
744
  and writes nothing, so a dry run that passes means the real run will.
709
745
 
710
746
  ### Fetch the doc back by slug
@@ -785,6 +821,29 @@ BEFORE creating ANY new file, you MUST:
785
821
  4. Only create new files when NO suitable location exists
786
822
  ```
787
823
 
824
+ ### Modernize a messy docs folder (T14113)
825
+
826
+ To clean up a whole tree (task- or date-named files, duplicates, split
827
+ category folders), use `cleo docs modernize` instead of moving files by hand:
828
+
829
+ ```bash
830
+ cleo docs modernize docs --out plan.json # dry run: kind, slug, keep/rename/merge-into/delete + reasons
831
+ cleo docs modernize --apply --plan plan.json # apply the reviewed plan; prints a receipt runId
832
+ cleo docs modernize --rollback dm-20261028-150000-abc123 # reverse that run
833
+ cleo docs modernize --store # stored docs: re-kind, re-slug (old slug stays an alias), renumber colliding ADRs
834
+ ```
835
+
836
+ Ambiguous classify and merge calls are judged by System One
837
+ (`docs.modernize.classify`, `docs.modernize.merge`; rule fallback when it is
838
+ unreachable) and recorded on each plan row. Apply stores survivors, folds
839
+ duplicates in, supersedes the removed docs, re-points relative markdown links
840
+ at the new paths (they still render on GitHub; `--wikilinks` opts into
841
+ `[[slug]]` instead), records every link as a `links-to` graph edge, edits a
842
+ file the plan marks `keep` only by re-pointing the hrefs the plan lists as
843
+ `linkFixes` (`link-fix` rows, so apply never does more than the dry run
844
+ showed), and keeps every replaced byte under
845
+ `.cleo/modernize/<runId>/` for rollback.
846
+
788
847
  ---
789
848
 
790
849
  ## 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.6.1
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-02
19
21
  stability: stable
20
22
  ---
21
23
 
@@ -53,6 +55,36 @@ 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
+ **Previous tag (T14173).** The notes, the CHANGELOG section (`write-changelog`) and `release reconcile` start from the newest reachable lower tag whose GitHub Release published; a tag whose `release.yml` run failed before creating its release (a failed canary) is skipped, so its changesets and tasks land in the next release. A stable cut also skips every prerelease tag. When `gh` cannot read a release (auth, network), cut and `write-changelog` refuse rather than guess; reconcile keeps the tag.
68
+
69
+ **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.
70
+
71
+ **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.
72
+
73
+ - **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.
74
+ - **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`.
75
+ - **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.
76
+ - **Provenance:** the merge sweep reconciles the newest stable tag automatically once its GitHub release exists (ADR-099); there is no manual reconcile step.
77
+ - **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.
78
+ - **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.
79
+ - **Task status is reported, never gated.** Green CI on the sha is the gate; a pending task does not block the cut.
80
+ - **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.
81
+
82
+ **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.
83
+
84
+ **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>`.
85
+
86
+ The plan/open pipeline below stays for one release as a fallback; T14114 deletes it.
87
+
56
88
  ## Canonical Pipeline
57
89
 
58
90
  | Step | Verb / Workflow | Owns transition | Notes |
@@ -79,10 +111,10 @@ Optional validators (read-only / dry-run):
79
111
  | RLSE-001 | Version MUST be CalVer (`YYYY.MM.patch`) per ADR-065 — never SemVer. | `cleo release plan` rejects non-CalVer; exit 53. |
80
112
  | 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
113
  | 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`). |
114
+ | 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`. |
115
+ | 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
116
  | 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`. |
117
+ | 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
118
 
87
119
  ## Integration
88
120
 
@@ -101,11 +133,18 @@ cleo release open v2026.6.0 --no-commit-plan
101
133
  # 3. (Optional) Poll PR + CI status while the workflow runs.
102
134
  cleo release pr-status v2026.6.0
103
135
 
104
- # 4. After the release PR merges, tag explicitly (auto-tag is retired).
136
+ # 4. Before the tag, prove macOS on the owner's Mac (T14104): release-prepare
137
+ # runs no macOS shards. Check out the exact commit to tag, then:
138
+ node scripts/release-mac-smoke.mjs
139
+ # Builds it, snapshots the real stores into a sandbox (outside the backup
140
+ # rotation), runs the built CLI in a sandboxed HOME and writes evidence +
141
+ # SHA256SUMS to .cleo/release-smoke/<sha>/. Exit 0 = every command passed.
142
+
143
+ # 5. After the release PR merges, tag explicitly (auto-tag is retired).
105
144
  git tag -a v2026.6.0 -m "Release v2026.6.0"
106
145
  git push origin v2026.6.0
107
146
 
108
- # 5. Reconcile — runs automatically inside release-publish.yml.
147
+ # 6. Reconcile — runs automatically inside release-publish.yml.
109
148
  # Run manually only if backfilling a historical release.
110
149
  cleo release reconcile v2026.6.0
111
150
  ```
@@ -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.1",
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.36.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.6.1",
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,