@cleocode/cleo 2026.5.77 → 2026.5.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.5.77",
+  "version": "2026.5.79",
   "description": "CLEO CLI — the assembled product consuming @cleocode/core",
   "type": "module",
   "main": "./dist/cli/index.js",
@@ -29,17 +29,18 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
-    "@cleocode/caamp": "2026.5.77",
-    "@cleocode/animations": "2026.5.77",
-    "@cleocode/cant": "2026.5.77",
-    "@cleocode/contracts": "2026.5.77",
-    "@cleocode/lafs": "2026.5.77",
-    "@cleocode/nexus": "2026.5.77",
-    "@cleocode/playbooks": "2026.5.77",
-    "@cleocode/runtime": "2026.5.77"
+    "@cleocode/animations": "2026.5.79",
+    "@cleocode/caamp": "2026.5.79",
+    "@cleocode/contracts": "2026.5.79",
+    "@cleocode/lafs": "2026.5.79",
+    "@cleocode/cant": "2026.5.79",
+    "@cleocode/nexus": "2026.5.79",
+    "@cleocode/paths": "2026.5.79",
+    "@cleocode/playbooks": "2026.5.79",
+    "@cleocode/runtime": "2026.5.79"
   },
   "peerDependencies": {
-    "@cleocode/core": "2026.5.77"
+    "@cleocode/core": "2026.5.79"
   },
   "peerDependenciesMeta": {
     "@cleocode/core": {

package/templates/workflows/README.md

@@ -0,0 +1,157 @@
+# CLEO GitHub Actions workflow templates
+
+This directory contains CLEO's templated GitHub Actions workflows for the
+release pipeline defined in
+`.cleo/rcasd/T9345/research/SPEC-T9345-release-pipeline-v2.md`. Templates
+are project-agnostic: they ship with `{{PLACEHOLDER}}` markers that are
+resolved at scaffold time by `cleo init --workflows` (T9531) against the
+local `.cleo/project-context.json` and the ADR-061 tool resolver.
+
+## Template files
+
+| Template                          | SPEC section | Purpose                                                |
+|-----------------------------------|--------------|--------------------------------------------------------|
+| `release-prepare.yml.tmpl`        | §5.1         | Cut release branch, bump version, open bump-PR.        |
+| `release-publish.yml.tmpl`        | §5.2         | Publish + tag once the bump-PR is merged.              |
+| `release-fanout.yml.tmpl`         | §5.3         | Best-effort post-publish fanout (docs, docker, etc.).  |
+| `release-rollback.yml.tmpl`       | §5.4         | Rollback workflow (revert PR + npm deprecate + reconcile). |
+
+## Template contract
+
+- Templates MUST use `{{PLACEHOLDER}}` markers compatible with simple regex
+  substitution (`s/{{NAME}}/value/g`). They MUST NOT use Mustache, Handlebars,
+  or any nested-syntax templating engine — the scaffold step relies on
+  deterministic, single-pass regex replacement so a stale template can be
+  diffed cleanly against a re-render.
+- Placeholder names MUST be `UPPER_SNAKE_CASE` wrapped in double braces.
+- Templates MUST be ASCII-only outside of strings.
+- Templates MUST pass `actionlint` after substitution. The
+  `release-prepare-render.test.ts` snapshot test renders with sample values
+  and (if `actionlint` is on `PATH`) pipes the output through `actionlint -`
+  via `child_process.execSync`.
+
+## Placeholders
+
+All four templates draw from the same placeholder vocabulary. Unused
+placeholders for a given template are silently ignored by the scaffolder.
+
+| Placeholder           | Source                                                 | Default                              | Example                              |
+|-----------------------|--------------------------------------------------------|--------------------------------------|--------------------------------------|
+| `{{NODE_VERSION}}`    | `.cleo/project-context.json` `node.version`            | `22.x`                               | `"22.x"`                             |
+| `{{INSTALL_CMD}}`     | ADR-061 archetype defaults (`primaryType`-specific)    | `pnpm install --frozen-lockfile`     | `pnpm install --frozen-lockfile`     |
+| `{{LINT_CMD}}`        | ADR-061 `tool:lint` resolution                         | `pnpm run lint`                      | `pnpm biome ci .`                    |
+| `{{TYPECHECK_CMD}}`   | ADR-061 `tool:typecheck` resolution                    | `pnpm run typecheck`                 | `pnpm run typecheck`                 |
+| `{{TEST_CMD}}`        | ADR-061 `tool:test` resolution                         | `pnpm run test`                      | `pnpm run test`                      |
+| `{{BUILD_CMD}}`       | ADR-061 `tool:build` resolution                        | `pnpm run build`                     | `pnpm run build`                     |
+| `{{BRANCH_PREFIX}}`   | `release.branchPrefix` in `.cleo/config.json`          | `release`                            | `release`                            |
+| `{{PR_LABEL}}`        | `release.prLabel` in `.cleo/config.json`               | `release`                            | `release`                            |
+| `{{NPM_PUBLISH_CMD}}` | `release.npmPublishCmd` in `.cleo/config.json`         | `pnpm publish --access public --tag latest` | `pnpm publish -r --access public --tag latest` |
+| `{{PUBLISHERS}}`      | `release.publishers` in `.cleo/config.json`            | `npm`                                | `npm cargo`                          |
+| `{{DOCS_BUILD_CMD}}`  | `release.fanout.docsBuildCmd` in `.cleo/config.json`   | `pnpm run docs:build`                | `pnpm --filter @cleocode/docs run build` |
+| `{{ENABLE_DOCS_DEPLOY}}`     | `release.fanout.docsDeploy` in `.cleo/config.json`     | `false`                  | `true`                               |
+| `{{ENABLE_DOCKER_RETAG}}`    | `release.fanout.dockerRetag` in `.cleo/config.json`    | `false`                  | `true`                               |
+| `{{ENABLE_SENTINEL_NOTIFY}}` | `release.fanout.sentinelNotify` in `.cleo/config.json` | `false`                  | `true`                               |
+| `{{ENABLE_STUDIO_DEPLOY}}`   | `release.fanout.studioDeploy` in `.cleo/config.json`   | `false`                  | `true`                               |
+| `{{ENABLE_NIGHTLY_TRIGGER}}` | `release.fanout.nightlyTrigger` in `.cleo/config.json` | `false`                  | `true`                               |
+| `{{DOCKER_IMAGE}}`    | `release.fanout.dockerImage` in `.cleo/config.json`    | *(none — required if `dockerRetag=true`)* | `cleocode/cleo`                |
+| `{{DOCKER_HUB_USER}}` | `release.fanout.dockerHubUser` in `.cleo/config.json`  | *(none — required if `dockerRetag=true`)* | `cleocode`                     |
+| `{{SENTINEL_WEBHOOK_URL}}` | `release.fanout.sentinelWebhookUrl` in `.cleo/config.json` | *(none — required if `sentinelNotify=true`)* | `https://sentinel.example.com/hooks/release` |
+| `{{STUDIO_DEPLOY_HOOK}}` | `release.fanout.studioDeployHook` in `.cleo/config.json` | *(none — required if `studioDeploy=true`)*   | `https://studio.example.com/deploy`        |
+| `{{NPM_PACKAGES}}`    | `release.rollback.npmPackages` in `.cleo/config.json`  | *(none — required if `PUBLISHERS` contains `npm`)*   | `@cleocode/cleo @cleocode/core`            |
+| `{{CARGO_CRATES}}`    | `release.rollback.cargoCrates` in `.cleo/config.json`  | *(none — required if `PUBLISHERS` contains `cargo`)* | `cleo-core cleo-cli`                       |
+
+Source precedence (highest first):
+
+1. Explicit override in `.cleo/project-context.json` (ADR-061 §1).
+2. Project archetype default keyed on `primaryType` (e.g. `node` → `pnpm`,
+   `rust` → `cargo`, `python` → `uv`).
+3. Hard-coded fallback in the scaffolder.
+
+## GitHub permissions required per template
+
+| Template                     | `contents`      | `pull-requests` | `id-token`            | `packages`         | Other            |
+|------------------------------|-----------------|------------------|----------------------|--------------------|------------------|
+| `release-prepare.yml.tmpl`   | `write`         | `write`          | `write` (signed tags) | (MUST NOT request) | —                |
+| `release-publish.yml.tmpl`   | `write` (tag)   | `read`           | `write` (OIDC)        | `write` (publish job only) | —        |
+| `release-fanout.yml.tmpl`    | `read`          | —                | `write` (Pages, docs job only)* | —        | `pages: write`*  |
+| `release-rollback.yml.tmpl`  | `write` (revert + tag delete) | `write`          | —                     | `write` (npm deprecate) | —          |
+
+*Per-job — only granted to the job that needs it.
+
+## Required secrets
+
+| Template                     | Required secrets        | Optional secrets                                  |
+|------------------------------|-------------------------|---------------------------------------------------|
+| `release-prepare.yml.tmpl`   | `GITHUB_TOKEN` (auto)   | *(none)* — MUST NOT require `NPM_TOKEN` (R-210)   |
+| `release-publish.yml.tmpl`   | `GITHUB_TOKEN`, `NPM_TOKEN`, `ANTHROPIC_API_KEY` | `CARGO_TOKEN`, `PYPI_TOKEN`, `DOCKER_HUB_TOKEN` |
+| `release-fanout.yml.tmpl`    | `GITHUB_TOKEN` (auto)   | `DOCKER_HUB_TOKEN` (if `dockerRetag=true`), `SENTINEL_TOKEN` (if `sentinelNotify=true`), `STUDIO_DEPLOY_TOKEN` (if `studioDeploy=true`) |
+| `release-rollback.yml.tmpl`  | `GITHUB_TOKEN` (auto), `NPM_TOKEN` (if `PUBLISHERS` contains `npm`) | `CARGO_TOKEN` (if `PUBLISHERS` contains `cargo`) |
+
+## Scaffolding workflow
+
+```bash
+# Render the templates against the local project, writing to .github/workflows/.
+cleo init --workflows
+
+# Re-render after editing project-context.json or release config.
+cleo init --workflows --force
+```
+
+The scaffolder reads each `*.yml.tmpl` file in this directory, performs
+regex substitution against the placeholder vocabulary above, validates the
+result with `actionlint`, and writes the rendered YAML to
+`<project>/.github/workflows/<basename>.yml`. Existing files are NOT
+overwritten without `--force`.
+
+## Extending without forking
+
+Per SPEC R-260, downstream projects MAY layer customizations onto the
+rendered workflows via a sibling `.github/workflows/<basename>.overrides.yml`
+file (planned: `.workflow-overrides.yml` at repo root for cross-template
+overrides). The scaffolder merges overrides as a final pass; conflicts at
+the same YAML key path resolve to the override.
+
+Override examples (illustrative — full schema lands with T9531):
+
+```yaml
+# .github/workflows/release-prepare.overrides.yml
+jobs:
+  preflight:
+    steps:
+      - name: Project-specific cache warm
+        run: ./scripts/warm-cache.sh
+        timeout-minutes: 3
+```
+
+Overrides MUST NOT remove or relax any RFC2119 invariant from
+`SPEC-T9345-release-pipeline-v2.md`. The scaffolder rejects override files
+that drop required `timeout-minutes`, modify `concurrency.group`, or strip
+declared permissions.
+
+## Cross-references
+
+- SPEC: `.cleo/rcasd/T9345/research/SPEC-T9345-release-pipeline-v2.md`
+  - §5.1 → `release-prepare.yml.tmpl` *(T9532, landed)*
+  - §5.2 → `release-publish.yml.tmpl` *(T9533, landed)*
+  - §5.3 → `release-fanout.yml.tmpl` *(T9534, landed)*
+  - §5.4 → `release-rollback.yml.tmpl` *(T9535, current)*
+- ADR-061 (tool resolver): governs `tool:*` placeholder resolution.
+- ADR-073 (release pipeline v2): umbrella architectural decision.
+- T9531: `cleo init --workflows` scaffold command (consumes these templates).
+- T9532: `release-prepare.yml.tmpl` + README skeleton + snapshot test.
+- T9533: `release-publish.yml.tmpl` + README placeholders + snapshot test
+  (eliminates F6 tag-on-pre-merge-SHA race by construction).
+- T9534: `release-fanout.yml.tmpl` + 11 fanout placeholders + snapshot test
+  (five independent best-effort jobs gated on env toggles, every job
+  carries `continue-on-error: true` so fanout failures cannot mark the
+  release as failed; fanout jobs MUST NOT be required status checks per
+  R-244).
+- T9535: `release-rollback.yml.tmpl` + rollback placeholders (`NPM_PACKAGES`,
+  `CARGO_CRATES`) + snapshot test (current task — `workflow_dispatch`-only
+  rollback with 4 jobs `validate` → `revert` → `deprecate` →
+  `reconcile-rollback`. The `revert` job opens a revert PR against `main`
+  via `gh pr create --label rollback` — NEVER pushes directly to `main`
+  per ADR-065. The `deprecate` job is best-effort
+  (`continue-on-error: true`); reconcile runs whenever validate succeeded
+  so the provenance graph records the operator's intent even if a
+  downstream side-effect failed).

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

@@ -0,0 +1,214 @@
+# CLEO release pipeline — Best-effort fanout workflow.
+#
+# Generated from packages/cleo/templates/workflows/release-fanout.yml.tmpl by
+# `cleo init --workflows` (T9531). DO NOT EDIT the rendered file directly —
+# extend via `.workflow-overrides.yml` per SPEC-T9345 R-260.
+#
+# Implements SPEC-T9345-release-pipeline-v2.md §5.3 (R-240 — R-244, R-260 —
+# R-263). Triggers on `release: published` (the GitHub Release event, NOT
+# `release: created` which fires on drafts). Each downstream job is an
+# independent best-effort fanout — every job carries `continue-on-error:
+# true` so a failed docs deploy, docker retag, sentinel notify, studio
+# rebuild, or nightly trigger CANNOT mark the release itself as failed.
+# These jobs MUST NOT be configured as required status checks (R-244).
+#
+# Placeholders (replaced at scaffold time — see workflows/README.md):
+#   <NODE_VERSION>             Node.js version            (e.g. "22.x")
+#   <INSTALL_CMD>              Install command            (e.g. "pnpm install --frozen-lockfile")
+#   <DOCS_BUILD_CMD>           Docs build command         (e.g. "pnpm --filter @cleocode/docs run build")
+#   <ENABLE_DOCS_DEPLOY>       Toggle docs-deploy job     ("true" | "false")
+#   <ENABLE_DOCKER_RETAG>      Toggle docker-retag job    ("true" | "false")
+#   <ENABLE_SENTINEL_NOTIFY>   Toggle sentinel-notify job ("true" | "false")
+#   <ENABLE_STUDIO_DEPLOY>     Toggle studio-deploy job   ("true" | "false")
+#   <ENABLE_NIGHTLY_TRIGGER>   Toggle nightly-trigger job ("true" | "false")
+#   <DOCKER_IMAGE>             Docker image name          (e.g. "cleocode/cleo")
+#   <DOCKER_HUB_USER>          Docker Hub login user      (e.g. "cleocode")
+#   <SENTINEL_WEBHOOK_URL>     Sentinel webhook URL       (HTTPS)
+#   <STUDIO_DEPLOY_HOOK>       Studio deploy hook URL     (HTTPS)
+# (Angle-brackets in this doc comment are intentional — they avoid being
+#  substituted by the {{...}} regex pass. The placeholders below use {{...}}.)
+
+name: Release Fanout
+
+# R-240: trigger on `release: published` ONLY. Draft releases (which fire
+# `release: created`) MUST NOT trigger the fanout — operators expect this
+# to run AFTER the publish + tag workflow has shipped the artifacts.
+on:
+  release:
+    types: [published]
+
+# R-241: workflow-level grants the minimum read scope. Per-job permissions
+# escalate ONLY for the jobs that need them (e.g. `pages: write` for docs
+# deploy). No top-level write scope — fanout is intentionally read-only at
+# the workflow level.
+permissions:
+  contents: read
+
+# R-243: serialize fanouts against the same release tag. cancel-in-progress
+# is FALSE so an in-flight fanout completes rather than losing partial
+# work (e.g. a half-pushed docker tag).
+concurrency:
+  group: fanout-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+# R-262: bash everywhere — no cross-platform shell drift across the fanout
+# jobs (they all run on ubuntu-latest but the contract is explicit).
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # R-242 (1/5): deploy generated documentation site to GitHub Pages.
+  # continue-on-error: true so a docs-build regression cannot fail the
+  # release. Disabled by default — flip {{ENABLE_DOCS_DEPLOY}} to "true"
+  # at scaffold time. The flag is hoisted into env so the `if:` becomes a
+  # dynamic expression (avoids actionlint constant-expression warning).
+  docs-deploy:
+    name: Deploy docs to GitHub Pages
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 15
+    env:
+      ENABLE_DOCS_DEPLOY: '{{ENABLE_DOCS_DEPLOY}}'
+    if: ${{ env.ENABLE_DOCS_DEPLOY == 'true' }}
+    # R-241 (per-job): pages: write + id-token: write granted ONLY for the
+    # docs-deploy job — other fanout jobs MUST NOT inherit GitHub Pages
+    # write scope.
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      # R-263: third-party Actions pinned to major+minor.
+      - name: Checkout
+        uses: actions/checkout@v4.1
+        with:
+          fetch-depth: 1
+        timeout-minutes: 5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4.0
+        with:
+          node-version: '{{NODE_VERSION}}'
+        timeout-minutes: 3
+
+      - name: Install dependencies
+        run: {{INSTALL_CMD}}
+        timeout-minutes: 5
+
+      - name: Build docs
+        run: {{DOCS_BUILD_CMD}}
+        timeout-minutes: 10
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5.0
+        timeout-minutes: 2
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3.0
+        with:
+          path: docs/dist
+        timeout-minutes: 5
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4.0
+        timeout-minutes: 5
+
+  # R-242 (2/5): retag the published docker image to `latest`. Failure here
+  # does NOT roll back the release — operators can re-run manually.
+  docker-retag:
+    name: Retag docker image to latest
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 10
+    env:
+      ENABLE_DOCKER_RETAG: '{{ENABLE_DOCKER_RETAG}}'
+      DOCKER_IMAGE: '{{DOCKER_IMAGE}}'
+      DOCKER_HUB_USER: '{{DOCKER_HUB_USER}}'
+      VERSION: ${{ github.event.release.tag_name }}
+    if: ${{ env.ENABLE_DOCKER_RETAG == 'true' }}
+    steps:
+      - name: Log in to Docker Hub
+        run: |
+          set -euo pipefail
+          echo "${{ secrets.DOCKER_HUB_TOKEN }}" | \
+            docker login -u "$DOCKER_HUB_USER" --password-stdin
+        timeout-minutes: 3
+
+      - name: Pull, retag, push
+        run: |
+          set -euo pipefail
+          docker pull "${DOCKER_IMAGE}:${VERSION}"
+          docker tag "${DOCKER_IMAGE}:${VERSION}" "${DOCKER_IMAGE}:latest"
+          docker push "${DOCKER_IMAGE}:latest"
+        timeout-minutes: 5
+
+  # R-242 (3/5): POST a `release.published` event to the Sentinel webhook
+  # so downstream monitoring can pick the release up. Best-effort — a
+  # webhook outage MUST NOT mark the release as failed.
+  sentinel-notify:
+    name: Notify Sentinel of release
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 5
+    env:
+      ENABLE_SENTINEL_NOTIFY: '{{ENABLE_SENTINEL_NOTIFY}}'
+      SENTINEL_WEBHOOK_URL: '{{SENTINEL_WEBHOOK_URL}}'
+      SENTINEL_TOKEN: ${{ secrets.SENTINEL_TOKEN }}
+      VERSION: ${{ github.event.release.tag_name }}
+      RELEASE_URL: ${{ github.event.release.html_url }}
+    if: ${{ env.ENABLE_SENTINEL_NOTIFY == 'true' }}
+    steps:
+      - name: POST release.published to Sentinel
+        run: |
+          set -euo pipefail
+          curl -fSL -X POST "$SENTINEL_WEBHOOK_URL" \
+            -H 'Content-Type: application/json' \
+            -H "Authorization: Bearer ${SENTINEL_TOKEN}" \
+            -d "{\"event\":\"release.published\",\"version\":\"${VERSION}\",\"url\":\"${RELEASE_URL}\"}"
+        timeout-minutes: 3
+
+  # R-242 (4/5): trigger a Studio rebuild via deploy hook. Studio runs
+  # outside this repo, so this job is a fire-and-forget POST.
+  studio-deploy:
+    name: Trigger Studio rebuild
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 20
+    env:
+      ENABLE_STUDIO_DEPLOY: '{{ENABLE_STUDIO_DEPLOY}}'
+      STUDIO_DEPLOY_HOOK: '{{STUDIO_DEPLOY_HOOK}}'
+      STUDIO_DEPLOY_TOKEN: ${{ secrets.STUDIO_DEPLOY_TOKEN }}
+      VERSION: ${{ github.event.release.tag_name }}
+    if: ${{ env.ENABLE_STUDIO_DEPLOY == 'true' }}
+    steps:
+      - name: POST to Studio deploy hook
+        run: |
+          set -euo pipefail
+          curl -fSL -X POST "$STUDIO_DEPLOY_HOOK" \
+            -H "Authorization: Bearer ${STUDIO_DEPLOY_TOKEN}" \
+            -H 'Content-Type: application/json' \
+            -d "{\"version\":\"${VERSION}\"}"
+        timeout-minutes: 10
+
+  # R-242 (5/5): dispatch the nightly e2e workflow against the freshly
+  # published release version. Decoupled from the release path — a failed
+  # dispatch is logged but does NOT fail the release.
+  nightly-trigger:
+    name: Dispatch nightly e2e for release
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 3
+    env:
+      ENABLE_NIGHTLY_TRIGGER: '{{ENABLE_NIGHTLY_TRIGGER}}'
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      VERSION: ${{ github.event.release.tag_name }}
+    if: ${{ env.ENABLE_NIGHTLY_TRIGGER == 'true' }}
+    steps:
+      - name: Dispatch nightly e2e
+        run: |
+          set -euo pipefail
+          gh workflow run nightly-e2e.yml \
+            --repo "${{ github.repository }}" \
+            -f release_version="$VERSION"
+        timeout-minutes: 2