cool-workflow 0.1.88 → 0.1.90

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -295,3 +295,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 The host-facing surface tracks the CLI simplification to 6 commands (streaming on by default, vendor agent flags); the multi-agent control loop verbs and their MCP-tool mirrors are otherwise unchanged.
+
+## 0.1.89 (v0.1.89)
+
+The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo auto-detect + clean help); the multi-agent verbs and their MCP-tool mirrors are unchanged.
+
+0.1.90

package/docs/multi-agent-eval-replay-harness.7.md

@@ -329,3 +329,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No change in behavior in v0.1.88 (no harness code changed; the new `loop-control` state node and loop result nodes replay byte-identically through the existing normalize/replay machinery, and pre-0.1.88 snapshots load unchanged)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/multi-agent-operator-ux.7.md

@@ -341,3 +341,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (no operator-view code changed; the new sub-workflow `subRunId`/`subRunDir` and `loopRound` run-state fields surface read-only through the existing derived graph/dependency/evidence views, which neither fabricate state nor guess success)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/node-snapshot-diff-replay.7.md

@@ -162,3 +162,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 A new `loop-control` StateNodeKind now flows through per-node snapshot/diff/replay (loop decisions are recorded as deterministic, replay-stable nodes); `appendRunNode` was optimized to mutate `run.nodes` in place (O(1) per append vs O(N^2) churn) with byte-identical persisted state, so snapshot/replay digests are unchanged.
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/observability-cost-accounting.7.md

@@ -221,3 +221,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 Attestation now signs the agent's RESULT, not just its usage: `TelemetryAttestationRecord.resultDigest` hash-binds sha256(result.md) into the ed25519-signed, hash-chained ledger so an offline re-verifier reconstructs the exact signed payload. Budget-aware loop scaling reads the SAME recorded usage total (`deriveUsageTotals`) the fail-closed cost cap reads, so a `until:{kind:"budget-target"}` loop stops on a token target while the cap stays the absolute backstop.
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-06-20 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-06-21 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.88`
-- Source modules: `65`
+- Version: `0.1.90`
+- Source modules: `67`
 - Workflow apps: `7`
-- Docs: `52`
-- Smoke tests: `128`
+- Docs: `53`
+- Smoke tests: `136`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -83,6 +83,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [agent-config.ts](../src/agent-config.ts)
 - [capability-core.ts](../src/capability-core.ts)
 - [capability-registry.ts](../src/capability-registry.ts)
+- [clones.ts](../src/clones.ts)
 - [collaboration.ts](../src/collaboration.ts)
 - [compare.ts](../src/compare.ts)
 - [contract-migration.ts](../src/contract-migration.ts)
@@ -102,6 +103,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [observability.ts](../src/observability.ts)
 - [onramp.ts](../src/onramp.ts)
 - [reclamation.ts](../src/reclamation.ts)
+- [remote-source.ts](../src/remote-source.ts)
 - [result-normalize.ts](../src/result-normalize.ts)
 - [run-export.ts](../src/run-export.ts)
 - [run-registry.ts](../src/run-registry.ts)
@@ -166,6 +168,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Release And Migration Discipline](release-and-migration.7.md)
 - [Cool Workflow Release History](release-history.md)
 - [Release Tooling](release-tooling.7.md)
+- [Remote-Source Review (`--link`)](remote-source-review.7.md)
 - [Verifiable Report Bundle](report-verifiable-bundle.7.md)
 - [Routines](routines.md)
 - [Run Registry / Control Plane](run-registry-control-plane.7.md)
@@ -203,9 +206,13 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [candidate-scoring-smoke.js](../test/candidate-scoring-smoke.js)
 - [canonical-workflow-apps-smoke.js](../test/canonical-workflow-apps-smoke.js)
 - [claude-p-agent-wrapper-smoke.js](../test/claude-p-agent-wrapper-smoke.js)
+- [cli-arg-parsing-smoke.js](../test/cli-arg-parsing-smoke.js)
 - [cli-command-surface-smoke.js](../test/cli-command-surface-smoke.js)
 - [cli-jsonmode-parity-smoke.js](../test/cli-jsonmode-parity-smoke.js)
 - [cli-mcp-parity-smoke.js](../test/cli-mcp-parity-smoke.js)
+- [cli-progress-summary-smoke.js](../test/cli-progress-summary-smoke.js)
+- [cli-recoverable-errors-smoke.js](../test/cli-recoverable-errors-smoke.js)
+- [clones-gc-smoke.js](../test/clones-gc-smoke.js)
 - [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
@@ -231,6 +238,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [freebsd-audit-fixes-smoke.js](../test/freebsd-audit-fixes-smoke.js)
 - [gemini-agent-wrapper-smoke.js](../test/gemini-agent-wrapper-smoke.js)
 - [h7-custom-profile-persist-smoke.js](../test/h7-custom-profile-persist-smoke.js)
+- [headline-commands-smoke.js](../test/headline-commands-smoke.js)
 - [incremental-resume-smoke.js](../test/incremental-resume-smoke.js)
 - [loop-bounded-expansion-smoke.js](../test/loop-bounded-expansion-smoke.js)
 - [mcp-app-surface-smoke.js](../test/mcp-app-surface-smoke.js)
@@ -247,6 +255,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [multi-agent-trust-policy-audit-smoke.js](../test/multi-agent-trust-policy-audit-smoke.js)
 - [no-false-green-smoke.js](../test/no-false-green-smoke.js)
 - [node-snapshot-diff-replay-smoke.js](../test/node-snapshot-diff-replay-smoke.js)
+- [npm-global-install-smoke.js](../test/npm-global-install-smoke.js)
 - [npm-trusted-publish-smoke.js](../test/npm-trusted-publish-smoke.js)
 - [observability-cost-accounting-smoke.js](../test/observability-cost-accounting-smoke.js)
 - [one-way-boundary-smoke.js](../test/one-way-boundary-smoke.js)
@@ -270,6 +279,8 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-smoke.js)
 - [release-tooling-smoke.js](../test/release-tooling-smoke.js)
+- [remote-link-archive-smoke.js](../test/remote-link-archive-smoke.js)
+- [remote-link-git-smoke.js](../test/remote-link-git-smoke.js)
 - [report-bundle-smoke.js](../test/report-bundle-smoke.js)
 - [report-verify-bundle-smoke.js](../test/report-verify-bundle-smoke.js)
 - [result-normalize-smoke.js](../test/result-normalize-smoke.js)

package/docs/real-execution-backends.7.md

@@ -169,3 +169,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (the container/remote/ci delegating integrations and their canonical evidence are unchanged; the streaming-default and incremental-resume work this release lives in the agent execution path and the drive, not in these backends)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/release-and-migration.7.md

@@ -309,3 +309,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (`release:check` and the durable run-state compatibility/`state check` path are unchanged; this release's release-flow verdict-capture work lives in the Release Tooling scripts, not in the release-check or migration discipline)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/release-tooling.7.md

@@ -247,3 +247,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 The release flow now captures the reviewer's verdict from agent stdout (`release-flow.js`), so the cut records the gate decision deterministically instead of relying on a hand-entered verdict; the kernel runtime stays untouched.
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/remote-source-review.7.md

@@ -0,0 +1,88 @@
+# Remote-Source Review (`--link`)
+
+CW v0.1.91 lets you point a review at **any repository on the internet** instead
+of only a local path: `cw -q "what are the risks?" --link <url>`. CW materializes
+the remote into a local checkout and runs the **existing** review pipeline against
+it — identical downstream to reviewing a folder. A URL passed to `-dir`/`--repo`
+is auto-detected, so `--link <url>` and `-dir <url>` are equivalent.
+
+```bash
+cw -q "What are the risks?" --link https://github.com/owner/repo
+cw -q "What are the risks?" --link git@gitlab.com:owner/repo.git --ref v1.2.0
+cw -q "What are the risks?" --link https://github.com/owner/repo/archive/refs/heads/main.tar.gz
+cw -q "..." --link <url> --check     # validate the URL + tooling WITHOUT fetching
+```
+
+## Sources
+
+- **Git repositories**, any host: `https://`, `http://`, `ssh://`, `git://`, the
+  scp-style `git@host:owner/repo`, and `file://`. Cloned shallow (`--depth 1
+  --single-branch`); `--ref <branch|tag>` selects a ref. `commit` is the resolved
+  `HEAD` SHA.
+- **Downloadable archives**: `.tar.gz` / `.tgz` / `.tar` / `.zip` (e.g. a GitHub
+  "Download ZIP" / codeload tarball). Fetched, extracted, and `git init`-snapshotted
+  into a local repo so the git-tracked source-context reader works unchanged.
+  `commit` is the **sha256 of the downloaded bytes** (a content address — there is
+  no git SHA).
+
+## The red line — materialize source, do not internalize execution
+
+`--link` only materializes the **source** to review. CW still **DELEGATES** worker
+execution to the operator's configured agent backend (`claude -p`, `codex exec`, an
+HTTP endpoint) exactly as a local review does; it never executes a model itself.
+Cloning is non-deterministic network I/O, so it happens in the **capability layer**
+(before `plan`), never in the replay-deterministic orchestrator core — which only
+ever sees the resulting local path.
+
+## Provenance — where the code came from, tamper-evidently
+
+The sanitized origin rides through three surfaces:
+
+- `run.inputs` → a `- Source: <url>@<commit>` line in `report.md`.
+- the `--json` result's `remote { url, commit, kind, ref, cached }`.
+- a hash-chained `source.clone` / `source.download` **trust-audit event** that
+  `cw audit verify <run-id>` re-proves — editing the recorded origin is detectable.
+
+Credentials in a URL (`https://user:token@host/…`) are stripped before the URL is
+used as a cache key, printed, persisted, or recorded; the raw URL reaches only a
+single `git` argv element. Git/download diagnostics are credential-redacted before
+they are ever surfaced.
+
+## Fail closed
+
+A bad URL, a blocked scheme, a network failure, or a credential-less private repo
+produces an **explicit error and a non-zero exit** — never a fabricated review,
+never a hang on an auth prompt (`GIT_TERMINAL_PROMPT=0`). Hardening:
+
+- **Scheme allowlist** (https/http/ssh/git/file); `ext::`/`fd::` transport helpers
+  and `-`-leading option-injection are rejected; the URL is always a separate argv
+  element (never a shell string); repo hooks are disabled (`-c core.hooksPath=`).
+- **Archive extraction** validates the entry listing for `..`/absolute traversal
+  BEFORE extracting, **rejects symlink/non-regular entries** (walked with `lstat`),
+  and bounds the decompression bomb by **declared** uncompressed size (gzip ISIZE /
+  `unzip -l`) before extracting and **actual** size (1 GiB) after.
+- **SSRF**: http(s) redirects are followed manually and each hop is re-validated
+  (http(s) scheme + no private/loopback/link-local host) before connecting — a
+  public URL cannot redirect CW into an internal service.
+
+## Cache — `cw clones`
+
+Checkouts are cached, content-addressed, under
+`~/.local/state/cool-workflow/clones/<hash>/` (honoring `CW_HOME`/`XDG_STATE_HOME`)
+and reused on the next question; `--refresh` re-fetches. Manage the cache:
+
+```bash
+cw clones list                          # origin url, kind, commit, age, bytes
+cw clones gc --older-than-days 30       # reclaim checkouts older than N days
+cw clones gc --all                      # reclaim everything
+```
+
+`cw clones gc` deletes only paths it has proven are inside the clones cache (fail
+closed). Both verbs have MCP peers (`cw_clones_list`, `cw_clones_gc`) with
+byte-identical payloads.
+
+## Determinism note
+
+The cache is keyed on the URL (+ref), not on content: if a URL's content changes
+upstream, the cached checkout is reused until `--refresh` (mirroring how a git
+clone pins its resolved `HEAD`). Use `--refresh` to re-fetch the latest.

package/docs/run-registry-control-plane.7.md

@@ -430,3 +430,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 Security: archive import now refuses path-traversal run ids (`..`/absolute/separator-bearing ids) before any run dir is minted, closing a write-outside-the-registry vector; run resolution and the run-state schema are otherwise unchanged.
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/run-retention-reclamation.7.md

@@ -220,3 +220,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (the tiered, append-only, cryptographically-verifiable reclamation transition is unchanged)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/state-explosion-management.7.md

@@ -298,3 +298,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (the summarization/compaction layer and its fail-closed derived summaries are untouched)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/team-collaboration.7.md

@@ -234,3 +234,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (the host-attested actor, append-only approvals/comments/handoffs, and the review gate that stacks on the verifier gate are unchanged)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/docs/web-desktop-workbench.7.md

@@ -242,3 +242,9 @@ npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-st
 ## 0.1.88 (v0.1.88)
 
 _No behavioral change in v0.1.88 (the five operator surfaces and the registry cross-run entry are unchanged; the Workbench still derives everything from state the CLI/MCP already expose)._
+
+## 0.1.89 (v0.1.89)
+
+_No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.1.88",
+    "version": "0.1.90",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -25,7 +25,7 @@
     },
     "runtime": {
       "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
-      "maxLines": 44000,
+      "maxLines": 48000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.88",
+      "Cool Workflow v0.1.90",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.1.88");
+    assert.equal(summary.version, "0.1.90");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.1.88");
+    assert.equal(shown.app.version, "0.1.90");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.1.88");
+    assert.equal(state.workflow.app.version, "0.1.90");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
 
-const TARGET_VERSION = "0.1.88";
+const TARGET_VERSION = "0.1.90";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.88");
+    assert.equal(appValidation.summary.version, "0.1.90");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.88 end-to-end golden path."
+        "Prove the deterministic v0.1.90 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.88");
+    assert.equal(state.workflow.app.version, "0.1.90");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.88/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.90/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/release-gate.sh

@@ -51,7 +51,7 @@ if [[ -n "$PREV_TAG" ]]; then
   TESTS_CHANGED=$(git diff --name-only "$RANGE" | grep -cE '\.(test|spec)\.|/tests?/' || true)
   [[ "$TESTS_CHANGED" -gt 0 ]] || fail "zero test changes since $PREV_TAG"
 
-  # --- 4. Cadence: >=4 cycles logged OR >=24h since previous tag -------
+  # --- 4. Cadence: >=4 cycles logged OR >=24h since previous tag, or a recorded HOTFIX ---
   say "[5/6] cadence"
   CYCLES=0
   if [[ -f ITERATION_LOG.md && -n "$PREV_TAG" ]]; then
@@ -60,8 +60,17 @@ if [[ -n "$PREV_TAG" ]]; then
   PREV_TS=$(git log -1 --format=%ct "$PREV_TAG")
   NOW_TS=$(date +%s)
   HOURS=$(( (NOW_TS - PREV_TS) / 3600 ))
+  # Hotfix path: an urgent fix may ship inside the cadence window, but ONLY via an
+  # EXPLICIT, RECORDED declaration — a "HOTFIX:" line added to ITERATION_LOG.md in this
+  # release range, carrying a reason. It is committed (auditable in the tag's history)
+  # and echoed here, so the bypass is never silent and a reviewer sees the reason.
+  HOTFIX="$(git diff "$RANGE" -- ITERATION_LOG.md | grep -E '^\+.*HOTFIX:' | head -1 | sed -E 's/^\+[[:space:]]*//' || true)"
   if [[ "$CYCLES" -lt 4 && "$HOURS" -lt 24 ]]; then
-    fail "cadence: only $CYCLES cycles logged and ${HOURS}h since $PREV_TAG (need >=4 cycles or >=24h)"
+    if [[ -n "$HOTFIX" ]]; then
+      say "  cadence bypassed by recorded HOTFIX (${HOURS}h, ${CYCLES} cycle-lines): ${HOTFIX}"
+    else
+      fail "cadence: only $CYCLES cycles logged and ${HOURS}h since $PREV_TAG (need >=4 cycles, >=24h, or a recorded 'HOTFIX:' line in ITERATION_LOG.md)"
+    fi
   fi
 else
   say "[3-5/6] no previous tag; substance/evidence/cadence checks skipped"