@sylad/cadence 1.10.0 → 1.11.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.10.0",
+      "version": "1.11.0",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/docs/deliver.md

@@ -165,7 +165,7 @@ cadence deliver --sha 6b0d9aa -- api                                  # an earli
 ```
 
 `--sha` (any mode) delivers a pushed commit other than `HEAD` — for a CI that
-builds each service only on the commit that touched it. `allowDirty` suits a
+builds each service only on the commit that touched it. To deliver an earlier commit while `HEAD` holds work that must not ship, push that sha alone first (`git push origin <sha>:main`), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`: with `ci: github` the wait is for the run of that exact sha, and GitHub only builds the tip of a push (L334, the `deliver` skill says so). The push goes to the branch delivered (`main` here); skip it when the sha is already on a remote branch, and when it is refused as non-fast-forward never force it (that would rewind the remote branch): the sha is not deliverable that way, stop and ask. `allowDirty` suits a
 working tree shared by several sessions when the delivery starts from a pushed
 sha and never from local files; without it a modified tree is refused. `--sha`
 itself never reads the working tree: a tracked file modified outside the delivered

package/docs/overview.md

@@ -51,7 +51,7 @@ The repository is its own [Claude Code](https://claude.com/claude-code) plugin m
 
 ```
 /plugin marketplace add Sylad/cadence
-/plugin install cadence@cadence        # skills /cadence:session-start, session-close, deliver, lead + the three reviewer agents
+/plugin install cadence@cadence        # skills /cadence:session-start, session-close, deliver, lead, orchestrate + the three reviewer agents
 /plugin install cadence-hud@cadence    # the status band above the prompt
 ```
 

package/docs/skills.md

@@ -10,7 +10,7 @@ As a plugin:
 ```
 
 gives `/cadence:session-start`, `/cadence:session-close`, `/cadence:deliver`,
-`/cadence:lead` and the `ux-reviewer`, `code-reviewer` and `qa-reviewer` agents. Or copy them into the
+`/cadence:lead`, `/cadence:orchestrate` and the `ux-reviewer`, `code-reviewer` and `qa-reviewer` agents. Or copy them into the
 repository with `cadence skills install` (to `.claude/skills/cadence-*` and
 `.claude/agents/cadence-*.md`; `--dir` for another `.claude` folder,
 `--force` to overwrite local edits).
@@ -43,6 +43,7 @@ repository with `cadence skills install` (to `.claude/skills/cadence-*` and
   subagents as the session cap at most (2 by default, `CADENCE_MAX_SESSIONS`), the ones it starts by hand declared with `cadence lead hold`, never two in the same repository. The whole flow is drawn in
   [docs/lead.md](lead.md); how a lot, a wave, the lead and the service of cadence itself fit together, in four figures, is in
   [docs/fonctionnement.md](fonctionnement.md).
+- **orchestrate**: the command line of a wave without going through `lead` — `cadence orchestrate <project>:<lot>[@<model>]` (a lot id with « / » kept as is, no `--lot` or `--model` option) and the resume with `--resume [--wave <wave>]`; the description triggers on « lancer une vague orchestrate ».
 - **ux-reviewer** (agent): captures at 1440 and 390 px, findings grounded in a
   named rule (Nielsen, WCAG 2.2 AA) or a measurement, ranked, turned into
   `raf add --parent` sub-tasks, and a one-line verdict for `raf ux`. It never

package/docs/whats-new.md

@@ -4,6 +4,7 @@
 
 ## In two lines
 
+- **1.11.0**: a new `orchestrate` skill gives the command line of a wave without `/lead`; the `deliver` skill says how to deliver a commit that is not `HEAD` (push that sha alone first, never forced).
 - **1.10.0**: the worktree mode of `cadence orchestrate` needs only the `orchestrate.worktrees` key and is on for cadence itself; the gate plays `orchestrate.build` before the tests, and `lead tour` flags a missing `orchestrate.test`.
   A lot waiting for a slot obeys `--drop` and `--stop-after-current`, the pre-check is back on Sonnet, `cadence perf` classes red deliveries, and the README is a short home page again.
 - **1.9.0**: the plan lives at `.cadence/raf.yaml` (`raf migrate`); `cadence ref` reads reference documents; `doc-keeper` agent, `orchestrate.testGate`, `cadence lead hold` shown by `cadence-hud`.
@@ -29,6 +30,8 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.11.0**: the plugin eval of 1.10.0 found two gaps in the skills, both closed and replayed at 1.00. A new `orchestrate` skill (L335, `docs/skills.md`) carries the command line of `cadence orchestrate` — `<project>:<lot>[@<model>]`, a lot id with « / » kept as is, `--resume` with or without `--wave` — so that an agent reaches it without `/lead` instead of inventing `--lot` and `--model`. The `deliver` skill (L334, `docs/deliver.md`) says how to deliver a commit that is not `HEAD`: push that sha alone (`git push origin <sha>:main`), then `cadence deliver --dry-run --sha <sha>` and `cadence deliver --sha <sha>`, because with `ci: github` the wait is for the run of that exact sha and GitHub only builds the tip of a push; skip the push when the sha is already on a remote branch, and never force a push refused as non-fast-forward.
+
 **1.10.0**: the worktree mode of `cadence orchestrate` (one git worktree per lot, independent lots of one repository in parallel) is no longer behind `CADENCE_EXPERIMENTAL_WORKTREES=1`: the `orchestrate.worktrees` key alone is the switch, on start and on `--resume`, `--integrate`, `--replay` and `--continue`, and cadence's own `cadence.yaml` turns it on after the trials L310 and L316 (L320); a red at the integrated tip is played once more before the lot is handed back, and the refusal names the red tests (L328); a union of the `CHANGELOG.md` entries of parallel lots, which accepts that a lot rewrites its own entry (L314, L323), and a kept branch recovered without the pre-check (L311). The gate of the wave plays `orchestrate.build` before `orchestrate.test`, a red build handing the lot back as a « build » finding (L333); `cadence lead tour` and `cadence orchestrate --dry-run` flag a project without `orchestrate.test` and name the probable command (L327). The pre-check is back on Sonnet in cadence's own configuration after the local model failed on about one lot in three, skips a lot created after the last code commit of the repository, and `cadence perf` measures it per lot (L322, L328). A lot waiting for a session slot obeys `--drop` and `--stop-after-current` (L332); `--resume` without a wave resumes the only unfinished one and is refused when several are (L309). `cadence perf` classes the red deliveries written before the class from their text (L331) and names the step that carries a rise of the tokens per lot (L312). `npm run service` purges the old copies put in service (L330), `cadence deliver` keeps a Ctrl-C (L325, L329), and `raf docs-ok` acknowledges a `docs.sync` gap (L317); `raf check` no longer reports two false drifts (L321). `cadence ref analyse` reads a reference document, `cadence ref diff` reconciles two readings and `--double` reads twice, an option (L265, L266); `cadence ref add` cites a range of figures and no longer reads « code figure n » as a citation (L274, L313); a failing PDF tool is a refusal, not a stack trace (L275). The README is a short home page again, the detail having moved to `docs/overview.md` (L326). Details: [CHANGELOG.md](../CHANGELOG.md).
 
 **1.9.0**: the default plan is `.cadence/raf.yaml`, a hidden folder git versions and `docs/` never publishes (L246), and `raf migrate [--dry-run]` moves a legacy plan and the readers of the old path (L284, L305); `raf title`, `raf visible`, `uses:` resources shown by `lead tour` and the lot `goal:` (L244, L273, L251–L253, L258). `cadence ref add|measure|check|corpus|eval` registers reference documents outside the repository, measures a rendered zone, validates the inventory schema and scores a reading against a known truth (L261–L264). In `cadence orchestrate`: the `doc-keeper` agent and `docs.articles` (L306, L308), the mechanical `orchestrate.testGate` before the review (L287), `precheck: local` on every lot with no commit (L296), a write-step time limit proportioned to the lot (L298), sessions that no longer hold their slot after their report (L285), the real weekly-limit message recognised (L286), and an experimental worktree mode with `--resume --integrate|--replay` and `--remove-worktree` (L279, L299–L304). `cadence lead hold|release` counts the lead's hand-started sessions, an expired one is flagged by `lead tour`, `--status` and the `cadence-hud` band (0.5.0; L255, L276, L278). `cadence deliver --sha` is accepted while a wave runs (L277), `CADENCE_DEPLOYED_FILE` names the deployed sha (L277, L281) and `deliveries-failed.log` keeps the class and last lines of a red delivery, secrets masked (L282, L289, L294). `cadence perf` breaks red deliveries down and counts the `review-small` UX (L282, L283). Details: [CHANGELOG.md](../CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",

package/skills/deliver/SKILL.md

@@ -32,10 +32,33 @@ writes that sha into the file named by `$CADENCE_DEPLOYED_FILE`: cadence logs it
 (a content that is not a hexadecimal commit sha — `HEAD` or a branch name included — fails the delivery; empty during a wave, the log keeps `$CADENCE_SHA` and a warning
 says the head moved).
 
-Its arguments go after `--`: `cadence deliver -- api frontend` (`--sha <rev>` to deliver a pushed
-commit other than HEAD). Ask the human (or the project's own
+Its arguments go after `--`: `cadence deliver -- api frontend` (`--sha <rev>` to deliver a commit
+other than HEAD, see « Delivering a commit that is not HEAD »). Ask the human (or the project's own
 delivery skill) which arguments this delivery needs; never guess them.
 
+## Delivering a commit that is not HEAD
+
+When HEAD holds work that must not ship and an earlier commit must, push **that sha alone** first,
+then deliver it:
+
+```sh
+git push origin <sha>:main
+cadence deliver --dry-run --sha <sha>
+cadence deliver --sha <sha>
+```
+
+The order matters. With `ci: github`, cadence waits for the run of that exact sha, and GitHub only
+builds the tip of a push: a sha that was never pushed as the tip has no run to wait for. Pushing HEAD
+instead would ship the unfinished work; never reset HEAD to get there.
+
+The push targets the branch being delivered (`main` here). Two cases where it does not apply:
+
+- The sha is already on a remote branch: skip the push, it is useless. A sha that was pushed earlier has a CI run
+  only if it was the tip of a push; if it never was, no run exists to wait for.
+- The push is refused as non-fast-forward (the sha is not a descendant of `origin/main`, or `origin/main`
+  has moved past it): **never force it**, `--force` would rewind the remote branch. The sha cannot be delivered
+  that way: stop and ask the human.
+
 ## Where to run
 
 Every `cadence` / `raf` command works on the git repository of the current directory. When the

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: orchestrate
+description: The exact command line of `cadence orchestrate` — launch a wave ("lancer une vague orchestrate", "start an orchestrate wave", run lot X with model Haiku) and resume it with `--resume [--wave <wave>]`. Use it before writing any `cadence orchestrate` command, without going through /lead. Syntax `<project>:<lot>[@<model>]`, a lot id with « / » kept as is.
+---
+
+# orchestrate — the command line of a wave
+
+`cadence orchestrate` runs one fresh short session per step of each lot (write, review, correction, delivery of
+the sheet). This page is only the syntax; the lead's workflow is the `cadence:lead` skill and every option is in
+`docs/orchestrate.md` of the cadence package.
+
+## Launch
+
+```sh
+cadence orchestrate <project>:<lot>[@<model>] [<project>:<lot>[@<model>] …] [--wave <id>] [--budget 2M]
+cadence orchestrate maritime-atlas:Q4/accueil-4-ux12@haiku
+cadence orchestrate finance-tracker:L41 cadence:L18@haiku --budget 1.5M
+```
+
+- One positional argument per lot: `<project>:<lot>`, then `@<model>` to give that lot a model (`@haiku`, `@sonnet`,
+  `@opus`). The project is what comes before the **first `:`**, the model what comes after the **last `@`**.
+- **A lot id may contain « / »** (sub-tasks of a plan kept read-only by another tool, `Q4/accueil-4-ux12`): write it as is, never escape
+  it, never replace it, never split it. Quote the whole argument only if the shell needs it.
+- There is no `--lot` and no `--model`: the lot and its model are always in the same argument, `<project>:<lot>@<model>`.
+  From inside a project, `cadence orchestrate L18` is enough.
+- `--dry-run` first when a precondition is in doubt (nothing is started); `--budget` takes `1.5M`, `800k` or `1500000`;
+  `--goal "<what done looks like>"` for a single lot whose title is stale.
+
+## Resume
+
+A wave that stopped (a question, the quota, an interruption) is resumed with the same program, never with a new wave:
+
+```sh
+cadence orchestrate --resume                     # the only unfinished wave of the folder
+cadence orchestrate --resume --wave <wave>       # a named wave (required when several are unfinished)
+cadence orchestrate --resume --wave <wave> --answer <project>:<lot> "reply"
+```
+
+`--resume` takes no lot: it replays the lots of the wave. `cadence orchestrate --status` shows the live waves of the machine and the table of the folder's latest wave; `--resume` with no wave lists the unfinished ones when there are several.