@1aboveio/skills 0.19.3 → 0.20.2

package/skills/engineering/rush-release/references/cut.md

@@ -8,10 +8,16 @@ along for the ride.
 ```bash
 node <skillsRoot>/rush-release/scripts/plan.mjs --sha <candidateSha> --json \
   > /tmp/rush-release-plan.json
+# Add --cloud-run when preflight selected cloud-run-staged.
 ```
 
 The plan names `baselineTag`, `currentVersion`, `bump`, `reason`,
-`nextVersion`, `tag`, `changelogMarkdown`, and `versionFiles`.
+`nextVersion`, final `tag`, optional `candidateTag`, `changelogMarkdown`, and
+`versionFiles`.
+
+Before showing the plan, use `git ls-remote --tags origin` to prove the proposed
+candidate and final tags are both unused remotely. Local tag discovery chooses
+the next RC ordinal; remote absence is the collision authority.
 
 SemVer (0.x treats breaking as minor unless the human asks for strict):
 
@@ -26,13 +32,24 @@ Changelog entries come from conventional-commit subjects in
 tag). Keep an existing `## [Unreleased]` body — derived entries merge with it,
 they do not replace it.
 
-## 2. Confirm
+## 2. Confirm once
 
-Show the frozen SHA, proposed version/tag, bump reason, changelog, version
-files, and publisher. Wait for confirmation. A different bump the human names
+Show the frozen SHA, proposed version/tag(s), bump reason, changelog, version
+files, publisher/deployment mode, and the complete outward-action sequence: create the cut
+branch/commit, push it, deliver its metadata PR through the queue, push the
+immutable tag(s), validate and conditionally promote Cloud Run when applicable,
+create a GitHub Release when required, and watch the publisher.
+Ask exactly one question. Its answer both settles any displayed unresolved
+choice and authorizes that entire sequence. A different bump the human names
 wins, as long as it is still SemVer.
 
 Do not create a branch, edit files, or tag before that confirmation.
+After it, proceed through publication without asking separate cut, merge, RC,
+exposure, tag, finalization, or publish questions. Repository/provider checks
+are gates the orchestrator evaluates, not reasons to ask the human to confirm
+facts. Ask again only by replacing the whole plan when its frozen SHA,
+version/tag, metadata diff, publisher, or outward actions change. A retry or
+resume of the unchanged plan inherits the original authorization.
 
 ## 3. Apply and commit
 

package/skills/engineering/rush-release/references/preflight.md

@@ -1,12 +1,15 @@
 # Preflight
 
-Preflight has three outputs: trunk `main`, the publisher to watch, and the
-files that carry the version. It does not pick the SHA, bump the version, or
-push.
+Preflight outputs trunk `main`, publishers, deployment mode, release commands,
+and the files that carry the version. It does not pick the SHA, bump the
+version, or push. Resolve these facts from repository and provider state without asking the
+human to confirm each one. If a required choice cannot be inferred, carry it
+into the single complete-plan question in [cut.md](cut.md); do not create a
+separate preflight confirmation.
 
 ## 1. Trunk
 
-Fetch `origin`. Confirm the release trunk is `main` from those fetched refs
+Fetch `origin/main` and all remote tags. Verify the release trunk is `main` from those fetched refs
 (`origin/main` exists). A repo whose production branch is `master` or `release`
 is not this workflow.
 
@@ -17,12 +20,28 @@ otherwise look at the tree:
 
 | Signal | Publisher |
 |---|---|
-| `cloudbuild.yaml` / `cloudbuild.json`, or a Cloud Build trigger on `v*` / `v*-rc.*` tags | `cloudbuild` |
+| Cloud Build production trigger matching only `v*-rc.*`, whose prod path emits immutable candidate coordinates after `--no-traffic` | `cloudbuild`, mode `cloud-run-staged` |
 | `package.json` with a publish workflow, `publishConfig`, or an explicit npm release | `npm` |
 | both | watch both |
 | neither, and the human did not name one | refuse — nothing to watch |
 
-Record `publisher` as `cloudbuild`, `npm`, or `both`. If a GitHub Actions
+Cloud Build presence alone is not a staged contract. For `cloud-run-staged`,
+verify from repository policy and live trigger configuration:
+
+- the production trigger matches RC tags and excludes the final `vX.Y.Z` tag;
+- each affected service deploys an immutable revision with `--no-traffic` and
+  publishes one receipt binding RC tag, merged SHA, revision, image digest, and
+  candidate URL;
+- `smoke.manifest.json` defines read-only `prod-preview` and `prod-active`
+  profiles with at least one eligible path;
+- exact inspect, traffic-shift, rollback, and candidate-delete commands are
+  documented, including service dependency order;
+- any durable processing affected by a shift has exact pause, quiescence,
+  resume, and restoration checks.
+
+Refuse staged release when any applicable item is absent; never improvise
+production commands. Record `publisher` as `cloudbuild`, `npm`, or `both` and
+`deploymentMode` as `artifact-only` or `cloud-run-staged`. If a GitHub Actions
 workflow publishes on `release: published` rather than on tag push, note that
 `gh release create` is required at publish time.
 

package/skills/engineering/rush-release/references/promotion.md

@@ -0,0 +1,70 @@
+# Cloud Run staged promotion
+
+Promote one immutable candidate from 0% to 100% under the complete-plan
+authorization. Load `smoke` for both validation profiles and the applicable
+platform skill for repository-declared Cloud Run commands. Do not restore the
+archived `resolve-release` state machine or introduce another confirmation.
+
+## 1. Bind the candidate
+
+After the RC-tag build reports `SUCCESS`, read its durable candidate receipt.
+For every affected service, independently verify from one fresh Cloud Run
+snapshot that:
+
+- receipt RC tag and source SHA equal the approved plan and `<mergedSha>`;
+- the named immutable revision runs the receipt's image digest;
+- the candidate URL resolves to that revision;
+- the candidate has exactly 0% traffic and the recorded incumbent exactly 100%;
+- no second release or unknown traffic-bearing revision is in flight.
+
+Missing, duplicate, stale, or contradictory identity is a pre-exposure failure.
+Delete the candidate by immutable revision only when the preflight contract
+declared that deletion safe; otherwise leave it at 0% and hand back. Never move
+the RC tag.
+
+## 2. Validate at 0%
+
+Run the repository's smoke workflow against the exact candidate URL with
+`--profile prod-preview`. Accept only a non-empty `ALIVE` verdict whose stamped
+target is that URL, profile is `prod-preview`, and `noMutations` is `true`.
+Record its `generatedAt`. A failed or unavailable gate leaves production on the
+incumbent and does not consume the final tag.
+
+## 3. Recheck and shift
+
+Immediately before exposure, re-read candidate identity and traffic. Require
+the candidate still at 0%, incumbent still at 100%, and the ALIVE verdict still
+within the plan's declared freshness window. If durable processing is affected,
+run the preflight-declared pause order and prove quiescence before traffic moves.
+
+Shift all affected services to the candidate in the declared dependency order.
+After each command, read traffic back. If a later service cannot shift, restore
+already-shifted services in reverse order before doing anything else. The plan's
+single confirmation already authorized this conditional shift and restoration.
+
+## 4. Verify live
+
+From fresh control-plane and service observations, require for every service:
+
+- the exact candidate revision holds 100% and the incumbent 0%;
+- serving source SHA and image digest equal the candidate receipt;
+- the live URL passes a non-empty, read-only `prod-active` smoke as `ALIVE`.
+
+Resume durable processing only against the verified serving candidate, then
+prove scheduling/admission and any required publication advancement are healthy.
+Only this state permits the final release tag.
+
+## 5. Failure routing
+
+- **Before any traffic moved:** production is untouched. Delete or retain the
+  0% candidate according to the recorded policy and hand back.
+- **After a known failed shift or live check:** automatically restore every
+  service to its recorded incumbent in reverse dependency order, restore
+  durable processing against that incumbent, and verify incumbent 100%,
+  candidate 0%, and `prod-active` ALIVE before hand-back.
+- **Ambiguous traffic, identity, or processing state:** stop all writes and hand
+  back the last known-good evidence for operator recovery. Never guess, retry a
+  shift, delete a revision, or claim rollback succeeded.
+
+The final tag remains unused on every failure path. An RC tag is immutable and
+remains as attempt evidence.

package/skills/engineering/rush-release/references/publish.md

@@ -1,8 +1,16 @@
 # Publish
 
-Push the cut, tag it, and watch the publisher. The tag is the deploy trigger
-in this lane, so a pushed tag that fails to ship **burns the version** — the
-next attempt takes the next patch. Do not move or delete the tag to "reuse" it.
+Push the cut, tag it, and watch the publisher. A pushed final tag that fails to
+publish **burns the version**. A Cloud Run RC tag that fails burns that RC
+ordinal, not the final version. Do not move or delete either tag to "reuse" it.
+
+The complete-plan confirmation in [cut.md](cut.md) already authorizes every
+action in this procedure and [promotion.md](promotion.md). Do not insert another
+confirmation before the branch push, PR queue, candidate validation, traffic
+shift, rollback, tag push, GitHub Release, or publisher watch. A provider or
+repository gate either passes and the sequence continues, or fails and the run
+hands back. If resolving a failure would change the approved identity or action
+set, return to planning and ask once on the replacement plan.
 
 ## 1. Push and merge the metadata PR
 
@@ -27,7 +35,7 @@ documented release path, a successful fast-forward of `<cutSha>` to `main`
 may use `<cutSha>` as `<mergedSha>`. Never infer this from local state: re-fetch
 and verify the remote ref.
 
-## 2. Verify and tag the merged main SHA
+## 2. Verify the merged main SHA
 
 The release tag must name a commit reachable from the remote default branch.
 This is the ancestry gate used by release publishers to refuse off-main
@@ -40,8 +48,6 @@ git merge-base --is-ancestor "<mergedSha>" origin/main
 test "$(git rev-parse "<cutSha>^{tree}")" = \
   "$(git rev-parse "<mergedSha>^{tree}")"
 test "$(git show "<mergedSha>:package.json" | jq -r .version)" = "<nextVersion>"
-git tag -a "<tag>" "<mergedSha>" -m "Release <tag>"
-git push --no-verify origin "refs/tags/<tag>"
 ```
 
 The tree equality check proves the provider merge introduced no post-freeze
@@ -52,6 +58,30 @@ when it is not `package.json`. Re-read the exact required queue/CI result for
 `<mergedSha>` before tagging. A green cut head is not evidence for a different
 merge commit.
 
+## 3. Publish by mode
+
+**Artifact-only:** create and push the final annotated tag on `<mergedSha>`,
+then continue to the publisher watch:
+
+```bash
+git tag -a "<tag>" "<mergedSha>" -m "Release <tag>"
+git push --no-verify origin "refs/tags/<tag>"
+```
+
+**Cloud Run staged:** create and push `<candidateTag>` on `<mergedSha>`. Watch
+Cloud Build until it emits the exact candidate receipt, then execute
+[promotion.md](promotion.md). Only after live verification succeeds, create and
+push the final tag on the same `<mergedSha>`. The final tag must not trigger a
+second Cloud Run build.
+
+```bash
+git tag -a "<candidateTag>" "<mergedSha>" -m "Candidate <candidateTag>"
+git push --no-verify origin "refs/tags/<candidateTag>"
+# After promotion.md succeeds:
+git tag -a "<tag>" "<mergedSha>" -m "Release <tag>"
+git push --no-verify origin "refs/tags/<tag>"
+```
+
 `--no-verify` is for tag refs, because a Mergify (or similar) pre-push hook
 that rewrites `git push` into a stack push is correct for branches and wrong
 for immutable tags.
@@ -64,19 +94,21 @@ If preflight recorded a workflow that publishes only on
 remote (`gh release create <tag> --notes-file …`). Otherwise the tag push is
 the trigger.
 
-## 3. Watch
+## 4. Watch
 
 Launch one background watcher; do not poll in the foreground.
 
-**Cloud Build** (`publisher` `cloudbuild` or `both`):
+**Cloud Build** (`publisher` `cloudbuild` or `both`) is watched first for the RC
+tag and exact merged SHA. `SUCCESS` means only that candidate production
+succeeded; Cloud Run success requires [promotion.md](promotion.md):
 
 ```bash
 gcloud builds list --limit=1 --format='value(id,status,substitutions.TAG_NAME)' \
-  --filter="substitutions.TAG_NAME=<tag> OR tags=<tag>"
+  --filter="substitutions.TAG_NAME=<candidateTag> OR tags=<candidateTag>"
 ```
 
-Success is `SUCCESS` for that tag. `FAILURE` / `TIMEOUT` / `CANCELLED` is a
-hand-back. Load `cloud-debug` only to diagnose, not to rerun the release.
+`FAILURE` / `TIMEOUT` / `CANCELLED` is a hand-back. Load `cloud-debug` only to
+diagnose, not to rerun the release.
 
 **npm** (`publisher` `npm` or `both`):
 
@@ -92,9 +124,10 @@ When a GitHub Actions workflow is the npm publisher, `gh run list` /
 `gh run watch` for the tag SHA is the wait; `npm view` remains the proof the
 artifact exists.
 
-## 4. Failure
+## 5. Failure
 
-If the watch fails, leave the tag in place and hand back: cut SHA, tag,
-publisher logs, and that the version is burned. Do not delete the tag, do not
-roll back production, and do not open a `resolve-release` traffic shift. A
-fix ships as the next patch from a new green HEAD.
+If an artifact watch fails after the final tag, leave it in place and hand
+back that the version is burned. If a staged candidate build fails, leave its
+RC tag, keep the final tag unused, and hand back with production untouched.
+Promotion failures follow [promotion.md](promotion.md). A fix starts from a new
+green HEAD and a replacement plan; tags are never moved or deleted.

package/skills/engineering/rush-release/scripts/plan.mjs

@@ -2,7 +2,7 @@
 // Changelog + SemVer plan from baseline tag..SHA.
 //
 // Usage:
-//   node plan.mjs --sha <sha> [--trunk main] [--json] [--strict]
+//   node plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run]
 //
 // Exit: 0 ok · 1 git/inspect failed · 2 usage
 import { existsSync, readFileSync } from 'node:fs'
@@ -50,6 +50,16 @@ export function latestReleaseTag(tags) {
   return parsed[parsed.length - 1]
 }
 
+export function nextReleaseCandidateTag(finalTag, tags) {
+  const escaped = finalTag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(`^${escaped}-rc\\.([1-9]\\d*)$`)
+  const ordinals = tags
+    .map((tag) => pattern.exec(tag))
+    .filter(Boolean)
+    .map((match) => Number(match[1]))
+  return `${finalTag}-rc.${ordinals.length ? Math.max(...ordinals) + 1 : 1}`
+}
+
 export function classifySubject(subject, body = '') {
   const title = String(subject || '').trim()
   const match = TITLE_RE.exec(title)
@@ -207,9 +217,16 @@ function parseLog(stdout) {
     })
 }
 
-export function planRelease({ sha, trunk = 'main', strict = false, cwd = process.cwd(), now = new Date() } = {}) {
+export function planRelease({
+  sha,
+  trunk = 'main',
+  strict = false,
+  cloudRun = false,
+  cwd = process.cwd(),
+  now = new Date(),
+} = {}) {
   if (!sha) {
-    const err = new Error('usage: plan.mjs --sha <sha> [--trunk main] [--json] [--strict]')
+    const err = new Error('usage: plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run]')
     err.exitCode = 2
     throw err
   }
@@ -230,6 +247,13 @@ export function planRelease({ sha, trunk = 'main', strict = false, cwd = process
   const { bump, reason } = bumpFor(changes, current, { strict })
   const next = nextVersion(current, bump)
   const version = formatVersion(next)
+  const tag = `v${version}`
+  const candidateTag = cloudRun
+    ? nextReleaseCandidateTag(tag, git(['tag', '--list', `${tag}-rc.*`], cwd)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean))
+    : null
   const date = now.toISOString().slice(0, 10)
   return {
     trunk,
@@ -239,7 +263,8 @@ export function planRelease({ sha, trunk = 'main', strict = false, cwd = process
     bump,
     reason,
     nextVersion: version,
-    tag: `v${version}`,
+    tag,
+    candidateTag,
     versionFiles: files,
     changes,
     date,
@@ -248,11 +273,12 @@ export function planRelease({ sha, trunk = 'main', strict = false, cwd = process
 }
 
 function parseArgs(argv) {
-  const opts = { json: false, strict: false, trunk: 'main', sha: null }
+  const opts = { json: false, strict: false, cloudRun: false, trunk: 'main', sha: null }
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
     if (arg === '--json') opts.json = true
     else if (arg === '--strict') opts.strict = true
+    else if (arg === '--cloud-run') opts.cloudRun = true
     else if (arg === '--sha') opts.sha = argv[++i]
     else if (arg === '--trunk') opts.trunk = argv[++i]
     else if (arg === '--help' || arg === '-h') opts.help = true
@@ -264,7 +290,7 @@ function parseArgs(argv) {
   }
   if (opts.help) return opts
   if (!opts.sha || !opts.trunk) {
-    const err = new Error('usage: plan.mjs --sha <sha> [--trunk main] [--json] [--strict]')
+    const err = new Error('usage: plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run]')
     err.exitCode = 2
     throw err
   }
@@ -274,7 +300,7 @@ function parseArgs(argv) {
 export function main(argv = process.argv.slice(2)) {
   const opts = parseArgs(argv)
   if (opts.help) {
-    process.stdout.write('plan.mjs --sha <sha> [--trunk main] [--json] [--strict]\n')
+    process.stdout.write('plan.mjs --sha <sha> [--trunk main] [--json] [--strict] [--cloud-run]\n')
     return 0
   }
   const result = planRelease(opts)

package/skills/engineering/smoke/SKILL.md

@@ -63,7 +63,7 @@ node <smoke>/scripts/smoke.mjs plan --manifest smoke.manifest.json --profile pro
 
 `--target` is now **just the address to drive against** (the deployed candidate/service URL; defaults to `local`) — it no longer participates in selection. The profile does. For a `local` profile, boot the build yourself the `/verify` way (a `run-*`/`verifier-*` skill in `.claude/skills/`, else the **`run`** skill, else cold-start from README/package.json, timebox ~15 min → BLOCKED); for a deployed profile, point `--target` at the revision and confirm it is the SHA you mean to verify.
 
-**Prod safety is mechanical, and it lives on the profile.** A path runs in a profile only if it declares that profile AND the profile's `mutationPolicy` admits it. The **production profiles (`prod-preview`, `prod-active`) are read-only** — every `mutates:true` path is excluded, **tenant or not** (a synthetic tenant still writes to the real production database, and a revision at 0% traffic is not a reason those writes are safe: `resolve-release` principle 4). `dev-active` allows a `mutates:true` path **only with a declared synthetic tenant**; the local profiles allow isolated writes. This is the old `--no-mutations` flag turned into a property of the *named profile*, so nobody has to remember to pass it — and because one name drives both the run and the verdict, the two **cannot disagree** about the selected set (the old run/verdict flag-mismatch is unrepresentable).
+**Prod safety is mechanical, and it lives on the profile.** A path runs in a profile only if it declares that profile AND the profile's `mutationPolicy` admits it. The **production profiles (`prod-preview`, `prod-active`) are read-only** — every `mutates:true` path is excluded, **tenant or not** (a synthetic tenant still writes to the real production database, and a revision at 0% traffic is not a reason those writes are safe). `dev-active` allows a `mutates:true` path **only with a declared synthetic tenant**; the local profiles allow isolated writes. This is the old `--no-mutations` flag turned into a property of the *named profile*, so nobody has to remember to pass it — and because one name drives both the run and the verdict, the two **cannot disagree** about the selected set (the old run/verdict flag-mismatch is unrepresentable).
 
 **Gate before promote.** On a deployed target the smoke is a gate only if it runs *before* the revision is irreversible — a smoke after traffic shifts is a monitor, not a gate. Deploy the candidate at **0% traffic** (stable, addressable) → smoke that URL under `prod-preview` → **promote only on ALIVE** → confirm the serving revision is the one you smoked, then re-smoke the live service under `prod-active`. Bonus: a DEAD is re-investigable against the same 0%-traffic revision with no rebuild — most of what a deployed smoke catches is config/secret/packaging. **Reuse the platform's deploy notification** (the CI/deploy build-failure → Pub/Sub/webhook path), carrying `smoke-verdict.json` so the alert names the broken path; the concrete placement lives in `cloud-build` / `cloud-deploy`.
 
@@ -82,7 +82,7 @@ node <smoke>/scripts/smoke.mjs verdict --manifest smoke.manifest.json --profile
 ```
 **ALIVE** iff every selected path PASSED. Any `fail`, `blocked`, or `missing` → **DEAD**, naming the path(s). Exit code is the gate (0 = ALIVE, 1 = DEAD). Selection is a pure function of `--profile` + the manifest, so the run and the verdict select the **same** set by construction — there is no second flag assembly for the verdict to disagree with, which is the whole point: the run/verdict mismatch that free-form targeting permitted is now unrepresentable.
 
-`smoke-verdict.json` is stamped with the facts an automated consumer needs to judge the evidence rather than trust it: **`profile`** (the Validation Profile it selected under), **`target`** (which URL it ran against), **`noMutations`** (DERIVED from the profile's `mutationPolicy` — `true` for the read-only production profiles), and **`generatedAt`** (an ISO-8601 instant — *when*, so a consumer can bound how old the evidence is). `resolve-release`'s traffic-shift gate compares these; an ALIVE from the wrong target, a mutating run, or too long ago is not a green light.
+`smoke-verdict.json` is stamped with the facts an automated consumer needs to judge the evidence rather than trust it: **`profile`** (the Validation Profile it selected under), **`target`** (which URL it ran against), **`noMutations`** (DERIVED from the profile's `mutationPolicy` — `true` for the read-only production profiles), and **`generatedAt`** (an ISO-8601 instant — *when*, so a consumer can bound how old the evidence is). `rush-release`'s traffic-shift gate compares these; an ALIVE from the wrong target, a mutating run, or too long ago is not a green light.
 
 **`generatedAt` dates the verdict, not the run.** `verdict` reduces whatever `--results` file you hand it, however old, and stamps the current instant on the result — so re-running `verdict` alone re-mints freshness without re-validating anything, and a consumer bounding the age cannot tell the difference. That is not a substitute for a stale gate's re-check: when what expired is the *evidence about a live target*, re-drive the paths into a new `smoke-results.json` — re-minting a verdict is not re-validation.
 
@@ -113,8 +113,8 @@ The **per-PR golden-path liveness floor** (`ensure-coverage` CI contract, gate 8
 - **CI (gate 8, blocking)** — wired in `e2e-test/assets/ci-gates.*`; boots the app, drives the paths into `smoke-results.json`, runs `smoke.mjs verdict`. The mechanical backstop.
 - **`resolve-issues`** — final step of the [epic integration gate](../resolve-issues/references/deliverables.md#deliverables-the-shippable-component-not-the-whole-epic): boot the assembled integration branch and run the golden paths; a DEAD whose broken paths are `fail` belongs to a specific unit → reopen its fix loop. **A DEAD built from `blocked`/`missing` paths is a gate-environment problem, not a unit's defect** — report it and fix the environment; reopening a fix loop on it spends a producer spawn and an adversarial review on code that is fine, and the round lands in the unit's budget all the same.
 - **`/smoke`** — standalone, any time, against `local` or a URL.
-- **`resolve-release`** — [the exposure gate](../resolve-release/SKILL.md#the-release-loop): the `prod-preview` profile against the 0%-traffic candidate URL (read-only, so it excludes every mutating path), then the `prod-active` profile against the live service after the shift. A DEAD **before** exposure deletes the candidate (no rollback, no user impact); a DEAD after it triggers the rollback policy.
-- **The dev-deploy recorder** (`cloud-build` → Post-deploy smoke gate) — the integration pipeline runs this gate after its 100%-traffic deploy and publishes the verdict as a **SHA-keyed commit status**, never failing the build; that recorded ALIVE is what `resolve-release` requires when pinning a release candidate (its principle 11).
+- **`rush-release` Cloud Run flow** — the `prod-preview` profile against the 0%-traffic candidate URL (read-only, so it excludes every mutating path), then the `prod-active` profile against the live service after the shift. A DEAD **before** exposure leaves production untouched; a DEAD after it triggers the recorded rollback policy.
+- **The dev-deploy recorder** (`cloud-build` → Post-deploy smoke gate) — the integration pipeline runs this gate after its 100%-traffic deploy and publishes the verdict as a **SHA-keyed commit status**, never failing the build; when configured as required CI, that recorded ALIVE helps `rush-release` select its green trunk SHA.
 
 ## Reference Map
 

package/skills/engineering/smoke/references/manifest.md

@@ -82,7 +82,7 @@ JSON (`smoke.manifest.json`). A repo may author in YAML and project to JSON —
 | `command` | cli | the command to run, for `cli` paths (alternative to `start`) |
 | `observable` | api/cli | the **concrete thing that proves the path worked** — the 200 body, the exit code. Required for `api`/`cli` (e2e-test doesn't cover them); for `browser` the referenced journey's assertions *are* the observable. |
 | `intent` | no | optional one-line human summary of what the browser journey proves — documentation only, not enforced. |
-| `mutates` | no | `true` if the path writes durable state. Forces a `tenant` and gates it out of read-only profiles. Under a **read-only profile** (any production profile), a tenant grants nothing: every `mutates:true` path is excluded regardless (`resolve-release` principle 4). |
+| `mutates` | no | `true` if the path writes durable state. Forces a `tenant` and gates it out of read-only profiles. Under a **read-only profile** (any production profile), a tenant grants nothing: every `mutates:true` path is excluded regardless. |
 | `tenant` | when `mutates` | a **synthetic/test tenant** id so the mutating path can run under a `synthetic-tenant` profile (e.g. `dev-active`) without touching real data. A `mutates:true` path with no `tenant` is excluded from a `synthetic-tenant` profile. This is **not** a production permit: the production database is real whether or not the revision serves traffic, so the read-only production profiles exclude the path either way. Name it with the **`e2e-` prefix** (`e2e-synthetic`) per the e2e-* account convention (`e2e-test` → `references/authoring/auth-flows.md`) — `validate` warns on an unprefixed tenant, because that's the one mistaken for live data. |
 | `profiles` | **when a `profiles` registry exists** | the [Validation Profiles](#validation-profiles-the-profiles-registry) this path is required in — a non-empty array of names from the registry. A path is only ever selected in a profile it declares; a path that declares none is a silent non-runner, so `validate` **fails closed** on it once a registry is present. (A per-path array, rather than the inverse profile→paths mapping, so a path's selection facts — `mutates`, `tenant`, `profiles` — all sit together on the path they govern.) |
 
@@ -123,11 +123,11 @@ Read-only paths always run in any profile they declare.
 | `prod-preview` | `pre-promotion` | `prod` | `preview` | `read-only` |
 | `prod-active` | `post-promotion` | `prod` | `active` | `read-only` |
 
-`resolve-release` consumes `prod-preview` at step 4a (validate the candidate at 0% traffic) and `prod-active` at step 4b (re-validate the live service after the shift). Each smoke **path** declares the profiles it is required in (`"profiles": ["pr-local", "prod-preview"]`); a path selected by zero eligible paths under a profile yields the existing **EMPTY** verdict — a gate that proves nothing must not look like a pass.
+`rush-release` consumes `prod-preview` before shifting the candidate from 0% traffic and `prod-active` after the shift. Each smoke **path** declares the profiles it is required in (`"profiles": ["pr-local", "prod-preview"]`); a path selected by zero eligible paths under a profile yields the existing **EMPTY** verdict — a gate that proves nothing must not look like a pass.
 
 **Recommended, not mandatory (for now).** A manifest with no `profiles` registry still `validate`s (legacy manifests don't break) but `validate` warns, and `plan`/`verdict --profile` cannot run against it. The moment a registry is present it is fully checked, and every path must declare its profiles.
 
-**Reserved names are pinned to their gate.** The five shipped names are consumed by `resolve-release` (and the other lanes) by **hardcoded string** — step 4a drives `--profile prod-preview`, 4b drives `prod-active` — so the name is itself a safety key, not just a label. `validate` therefore **pins each reserved name to its gate**: `pr-local`→`pull-request`, `queue-local`→`merge-queue`, `dev-active`→`trunk-integration`, `prod-preview`→`pre-promotion`, `prod-active`→`post-promotion`. From the gate, the `(environment, endpoint)` table and the prod-read-only rule force the rest — so an entry *named* `prod-preview` but *bound* to a writable dev gate **fails closed**, instead of letting `plan --profile prod-preview` inherit a `synthetic-tenant` write policy against the production candidate.
+**Reserved names are pinned to their gate.** The five shipped names are consumed by `rush-release` (and the other lanes) by **hardcoded string** — staged promotion drives `--profile prod-preview` before exposure and `prod-active` after — so the name is itself a safety key, not just a label. `validate` therefore **pins each reserved name to its gate**: `pr-local`→`pull-request`, `queue-local`→`merge-queue`, `dev-active`→`trunk-integration`, `prod-preview`→`pre-promotion`, `prod-active`→`post-promotion`. From the gate, the `(environment, endpoint)` table and the prod-read-only rule force the rest — so an entry *named* `prod-preview` but *bound* to a writable dev gate **fails closed**, instead of letting `plan --profile prod-preview` inherit a `synthetic-tenant` write policy against the production candidate.
 
 | Hazard | Failure mode | What to prove |
 |---|---|---|

package/skills/payment/payment-analysis/SKILL.md

@@ -12,7 +12,8 @@ description: >
   decline mix, BIN/issuer-country contribution, settlement GMV, payment journey,
   Sankey funnel, FX-to-USD, chargeback rate, 运营影响, or "business analysis of
   transactions" — even if they do not say payment-analysis. Do NOT use for
-  supervised fraud-rule mining (that is fraud-analysis).
+  supervised fraud-rule mining (fraud-analysis) or TLD / MCC-miscoding
+  clusters (tld-detection).
 ---
 
 # Payment Analysis
@@ -31,7 +32,7 @@ optional topic fuel, not required for the journey core.
 
 **Produce:** Markdown + preferred Chinese/bilingual HTML under
 `reports/payment-analysis/`.  
-**Do not produce:** supervised precision/recall packages (`fraud-analysis`).
+**Do not produce:** supervised precision/recall packages (`fraud-analysis`) or TLD clusters (`tld-detection`).
 
 Read the playbook for the step you are on. Paths under `references/` are
 relative to this skill.
@@ -106,12 +107,13 @@ Do not change numbers, joins, or chart data.
 - [ ] 运营影响 only from auth-rate-actions.md when triggered
 - [ ] Language matches terminology.md; banned strings have no unexplained hits
 
-## Boundary with fraud-analysis
+## Boundary with fraud-analysis and tld-detection
 
 | Need | Skill |
 |---|---|
 | Volume, journey Sankey, auth rate, decline mix, settlement overview, 运营影响 routing | `payment-analysis` |
 | Proxy/confirmed fraud labels, holdout precision/recall, 3DS/block **packages** | `fraud-analysis` |
+| Potential TLD clusters, currency-amount-pair ladders, MCC miscoding, stuffing | `tld-detection` |
 
 Routing 3DS / 风控拦截 / retry from this extract is not a fraud-analysis rule
 package.

package/skills/payment/tld-detection/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: tld-detection
+description: >
+  Explicit-only. Potential TLD (transaction-laundering) clusters from
+  descriptor partitions, then exact currency-amount pairs, with same-descriptor
+  baseline contrasts, high/medium/low risk tiers, exposure sizing, and a
+  ≤3-sentence decision.
+  Not payment-analysis or fraud-analysis.
+disable-model-invocation: true
+---
+
+# TLD Detection
+
+Find **potential TLD clusters** in an authorization extract. TLD here is
+transaction laundering, not a domain name: hidden activity stuffed under a
+normal MCC, often mixed across descriptors.
+
+First partition the cleaned authorizations by **descriptor**. Inside each
+descriptor, the clustering key is the **currency-amount-pair**. Geometric
+relationships between exact anchors are the stuffing signal (掺量). BIN
+country is not a membership key; report it in the cluster-versus-baseline
+comparison after membership is frozen.
+
+**Produce:** cluster results and a separate run-specific methodology document
+under `reports/tld-detection/`.
+**Do not produce:** confirmed laundering, a legal finding, or supervised
+fraud-rule packages (`fraud-analysis`).
+
+Paths under `references/` are relative to this skill.
+
+## Workflow
+
+Follow these steps in order. Detail:
+[references/workflow.md](references/workflow.md).
+
+| Step | Do | Gate |
+|---|---|---|
+| 0 Pre-flight | File, grain, columns, window | Stop if auth grain, descriptor, amount, or currency column is missing; caption missing BIN country |
+| 1 Clean | Dedup | Record drop counts; do not filter BIN country |
+| 2 Cluster | Partition; rank pairs; identify anchors; freeze exact keys; compare with same-descriptor baseline | Partition = descriptor; ≥3 levels; adjacent levels = 2x; ≥100 attempts; absolute residual cap per candidate currency |
+| 3 Risk | Assign high/medium/low investigation priority | Mixed BIN countries are neutral; exact 100% single-country concentration is a standout |
+| 4 Decision | Conclusion + basis for the book | ≤3 sentences; no new evidence |
+| 5 Report | Answer highest-risk, cluster-characteristic, and exposure questions; write + proofread | Sort high → medium → low; no confirmed-TLD wording |
+
+### 0 — Pre-flight
+
+Authorization extract, one row per auth attempt. Record paths, time field,
+amount, currency, BIN/issuer country, descriptor, MCC, response. Grain and
+column aliases: [workflow.md](references/workflow.md).
+
+### 1 — Clean
+
+[references/clean.md](references/clean.md). Deduplicate first. Do not
+FX-convert the clustering key. Do not drop non-US BIN rows.
+
+### 2 — Cluster
+
+[references/clustering.md](references/clustering.md). Build normalized
+descriptor partitions, then rank currency-amount-pairs inside each descriptor. Use
+`scripts/detect_ladders.py` to detect geometric anchor relationships with
+adjacent, currency-specific absolute residual caps. Every cluster must contain
+at least three theoretical levels with a fixed 2x relationship between adjacent
+levels (for example 1x, 2x, 4x, 8x); search both up and down from every candidate
+seed. A theoretical level may
+keep multiple exact anchors, but each additional anchor must clear the stated
+portfolio support floor. Freeze membership by exact descriptor, currency,
+and amount; keep only clusters with ≥100 authorization attempts. Compare each
+cluster with the baseline formed by removing that cluster from the same
+descriptor. Do not invent clusters from MCC or comparison features.
+
+### 3 — Risk
+
+[references/decision.md](references/decision.md). Assign every identified
+currency-amount pair exactly one investigation-priority tier: High, Medium,
+or Low. BIN-country mixture is neutral and never downgrades a cluster. Treat
+an exact 100% single-BIN-country cluster as a standout; separately report the
+cluster's share of that descriptor-country slice without using an arbitrary
+coverage threshold or risk points.
+
+### 4 — Decision
+
+Write the conclusion and the basis in **at most 3 sentences** for the whole
+book. A one-line table per cluster is allowed under that.
+
+### 5 — Report
+
+[references/report-template.md](references/report-template.md). Terms:
+[references/terminology.md](references/terminology.md).
+
+```text
+reports/tld-detection/<scope>_clusters.md
+reports/tld-detection/<scope>_clusters.zh.md
+reports/tld-detection/<scope>_clusters.zh.html
+reports/tld-detection/<scope>_methodology.md
+reports/tld-detection/<scope>_methodology.zh.md
+reports/tld-detection/<scope>_methodology.zh.html
+```
+
+Keep detection results in the cluster reports. Lead with the highest-risk
+clusters, characterize every identified cluster and its descriptor share, then
+quantify exposure by risk tier, descriptor, and across all authorization
+attempts. Sort High → Medium → Low, then by evidence strength and attempts
+inside each tier. Put the
+actual run's cleaning, partitioning, parameter selection, sensitivity evidence,
+baseline definition, and audit details in the methodology documents; link the
+paired files in both directions. HTML is preferred when there are charts. Grep
+banned strings after writing.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Freeze cleaned universe and descriptor partitions
+3. Assign High / Medium / Low risk tiers
+4. Publish descriptor currency-amount pairs + same-descriptor baselines
+5. Write ≤3-sentence decision
+6. Write report + separate run methodology and proofread
+
+## Boundary
+
+| Need | Skill |
+|---|---|
+| Potential TLD clusters, currency-amount pairs, stuffing / 掺量, MCC miscoding, descriptor mixing | `tld-detection` |
+| Volume, journey Sankey, auth rate, decline mix, settlement overview | `payment-analysis` |
+| Proxy/confirmed fraud labels, holdout precision/recall, rule packages | `fraud-analysis` |
+
+A suspected-fraud *rate contrast* in this skill is not a fraud-analysis
+rule package.
+
+## Reference index
+
+| Need | Read |
+|---|---|
+| Grain, columns, window | [workflow.md](references/workflow.md) |
+| Dedup | [clean.md](references/clean.md) |
+| Currency-amount pairs, anchors, same-descriptor baseline | [clustering.md](references/clustering.md) |
+| ≤3-sentence conclusion | [decision.md](references/decision.md) |
+| Report chapters | [report-template.md](references/report-template.md) |
+| Language / banned strings | [terminology.md](references/terminology.md) |
+
+## Sanity check
+
+- [ ] Auth grain; dedup counts are stated; no BIN-country row filter
+- [ ] Partition key is normalized descriptor; missing descriptor is an explicit bucket
+- [ ] Clustering key is original currency + amount, not USD
+- [ ] Each rung-pool currency has an explicit adjacent absolute-residual cap and sensitivity evidence
+- [ ] Multi-anchor levels state their portfolio support floor; final membership uses exact selected amount keys
+- [ ] Cluster attempts ≥100
+- [ ] Every cluster has a High / Medium / Low risk tier and results sort in that order
+- [ ] Currency-amount pairs show seed and representative anchors; `*` marks a multi-amount level
+- [ ] Same amount pair may recur across descriptor partitions; never merge them automatically
+- [ ] BIN country is post-membership reporting data, not a membership key; Mixed is neutral
+- [ ] Exact 100% single-country concentration is a standout; descriptor-country coverage is shown without a risk threshold
+- [ ] Each cluster baseline is the same descriptor after removing that cluster
+- [ ] Definition summary contains only descriptor, seed, anchors, and attempts
+- [ ] Anchor table reports attempts, authorization success rate, and suspected-fraud share for every level, including n < 30
+- [ ] Characteristics contain descriptor total, cluster attempts/share, MCC, and cluster-vs-baseline auth rate, suspected-fraud share, top 3 banks, and top 3 BIN countries
+- [ ] Decision prose is ≤3 sentences (conclusion + basis)
+- [ ] Report answers highest-risk, identified-cluster characteristics, and by-tier/by-descriptor exposure
+- [ ] Run-specific methodology is separate from results; report and methodology link to each other
+- [ ] Zero families → ranking only; no descriptor-invented clusters
+- [ ] Language matches terminology.md; no confirmed-laundering claim