@1aboveio/skills 0.20.1 → 0.20.3

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.
-- **Legacy `resolve-release` flow (archived)** — 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/similar-domain/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/payment/similar-domain/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: similar-domain
+description: >
+  Find the domains, mirrors, and operating entities related to one or more seed
+  domains: collect technical fingerprints (analytics IDs, block-page templates,
+  DNS, mail, certificates, registration), reverse-pivot on each fingerprint,
+  score every link, and expand until the cluster stops growing. Use whenever
+  the user gives a domain or URL and asks who is behind it, whether several
+  sites are related or the same operator, for sister sites, mirror domains,
+  the cluster, or a merchant-website background check — even if they never say
+  similar-domain. Stops at websites, mirrors and operators: anything inside
+  transaction data (streams, preset menus, amount ladders) is tld-detection,
+  and transaction-level fraud rules are fraud-analysis.
+---
+
+# Similar Domain
+
+Start from a seed domain and find every other domain that the same people run.
+A cluster is defined by **shared infrastructure**, not by shared branding or
+shared industry. Corporate records (operator, licence, affiliate program)
+confirm and name the cluster; they do not create it on their own.
+
+The method is a loop: read fingerprints off a domain, ask "who else has this?"
+for each fingerprint, score what comes back, and feed every new domain back
+into the loop.
+
+**Produce:** a scored cluster with an evidence matrix, the entity chain behind
+it, and a ≤3-sentence verdict, under `reports/similar-domain/`.
+**Do not produce:** an ownership claim with no corporate evidence, a cluster
+built from one weak signal, or a list of every site on the same CDN.
+
+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 | Seeds, question, jurisdiction, access limits | Stop if there is no resolvable domain; note geo-blocks and challenge pages |
+| 1 Fingerprint | Record every non-brand identifier on each domain | Every fingerprint has a source and a timestamp; local resolver artefacts are flagged |
+| 2 Pivot | Reverse-search each fingerprint for other domains | Each pivot is logged with source class and hit count; high-noise pivots are filtered by a second fingerprint |
+| 3 Expand names | Enumerate mirror and numbering variants of every brand found | Candidates are only kept if they share a fingerprint from step 1 |
+| 4 Entity | Operator, licence, address, affiliate program, terms page | Each entity fact cites a page; conflicting operator names are kept, not resolved by guess |
+| 5 Score | Weight every link; label each domain | Two independent strong signals for Confirmed; one for Probable; nothing weaker than Possible enters the cluster table |
+| 6 Loop | Send every new Confirmed or Probable domain back to step 1 | Stop when a full pass adds no new domain |
+| 7 Report | Verdict, cluster table, evidence matrix, entity chain, outliers, pivot log | ≤3-sentence verdict; no ownership wording without an entity citation |
+
+### 0 — Pre-flight
+
+Record the seed domains, what the user actually wants to know (same
+operator? mirrors? merchant background?), and any jurisdiction or time limits.
+Note what you cannot see: geo-blocks, bot challenges, private WHOIS. A blocked
+site still yields a block page, DNS, certificates, and history, so blocking is
+a finding, not a dead end. Grain and limits:
+[workflow.md](references/workflow.md).
+
+### 1 — Fingerprint
+
+[references/fingerprints.md](references/fingerprints.md). Collect
+everything about the domain that is not the brand name: registration facts,
+DNS and mail records, certificate history, analytics and pixel IDs, the
+block-page or error-page template, support-address pattern, hard-coded
+partner hosts, and naming scheme. Record each with where it came from.
+Fingerprint the seed fully before pivoting; a half-collected profile makes
+later pivots look independent when they are not.
+
+### 2 — Pivot
+
+[references/pivots.md](references/pivots.md). For each fingerprint, query the
+source class that can answer "who else has this": page-source indexes for
+analytics IDs and templates, passive DNS for nameservers and mail records,
+certificate transparency for subdomains and naming schemes, reverse WHOIS for
+registration batches. Ordinary web search does not index page source; do not
+treat an empty web-search result as a negative. Filter noisy pivots
+(shared CDN nameservers, common mail includes) by requiring a second
+fingerprint before a hit becomes a candidate.
+
+### 3 — Expand names
+
+Brands that rotate mirrors follow a scheme: numbered suffixes, hyphenated
+digits, double-dash prefixes, country TLDs. Enumerate the scheme for every
+brand found and keep only the variants that share a step-1 fingerprint.
+A name match alone is a candidate, never a member.
+
+### 4 — Entity
+
+[references/entities.md](references/entities.md). Once a brand name exists,
+collect the legal entity, licence number, address, and affiliate program from
+the site's own terms page and from review aggregators, then reverse each of
+those: licence registers list every domain under one licence, affiliate
+programs list every brand they pay for, entity names appear in other sites'
+terms pages. Keep conflicting operator names side by side with dates; operators
+migrate and the conflict is often the history.
+
+### 5 — Score
+
+[references/scoring.md](references/scoring.md). Weight each link by how hard
+it is to share by accident. One analytics account or one custom template is
+very strong; one registrar or one CDN nameserver pair is medium. Two signals
+from the same vendor account count once. Label each domain Confirmed,
+Probable, Possible, or Unrelated, and keep the reasoning visible in the
+evidence matrix.
+
+### 6 — Loop
+
+Every Confirmed or Probable domain becomes a new seed and goes through steps 1
+to 5. Possible domains are parked with the fingerprint that would promote them.
+Stop when a complete pass finds nothing new, or when the user's question is
+answered and further expansion would only add mirrors.
+
+### 7 — Report
+
+[references/report-template.md](references/report-template.md). Terms:
+[references/terminology.md](references/terminology.md).
+
+```text
+reports/similar-domain/<seed>_cluster.md
+```
+
+Lead with the verdict, then the cluster table sorted Confirmed → Probable →
+Possible, the evidence matrix (domain × fingerprint), the entity chain with
+dates, outliers that were checked and rejected, coverage caveats, and the
+pivot log. Grep banned strings after writing.
+
+## Progress
+
+Track a task plan. One item is `in_progress` at a time.
+
+1. Pass pre-flight
+2. Fingerprint every seed
+3. Run and log pivots
+4. Expand naming schemes
+5. Collect entity chain
+6. Score and label
+7. Loop until no new domain
+8. Write report and proofread
+
+## Boundary
+
+| Need | Skill |
+|---|---|
+| Related domains, mirrors, sister sites, who runs a website, merchant-site background | `similar-domain` |
+| Anything inside a transaction file: upstream streams behind a descriptor, wallet currency, preset menus, frozen-rate batches, retail constants, currency-amount ladders | `tld-detection` (`scripts/detect_streams.py`, then the ladder run) |
+| Supervised fraud labels, holdout precision/recall, rule packages | `fraud-analysis` |
+| Volume, journey, auth rate, decline mix | `payment-analysis` |
+
+A domain cluster from this skill can feed a merchant-risk decision; it is not
+itself a fraud finding. When the user also has authorization data for the
+merchant, hand that part to `tld-detection`: this skill stops at the websites,
+mirrors and operators.
+
+## Reference index
+
+| Need | Read |
+|---|---|
+| Inputs, limits, order that must not move | [workflow.md](references/workflow.md) |
+| What to collect per domain and why it identifies an operator | [fingerprints.md](references/fingerprints.md) |
+| Which source class answers each "who else" question, and the traps | [pivots.md](references/pivots.md) |
+| Operator, licence, affiliate, terms-page pivots | [entities.md](references/entities.md) |
+| Link weights, independence, labels | [scoring.md](references/scoring.md) |
+| Report chapters | [report-template.md](references/report-template.md) |
+| Language and banned strings | [terminology.md](references/terminology.md) |
+
+## Sanity check
+
+- [ ] Seeds, question, and access limits are stated; blocked sites are still fingerprinted
+- [ ] Every fingerprint has a source and a timestamp; local resolver artefacts are excluded
+- [ ] Every pivot is logged with source class, query, and hit count, including empty ones
+- [ ] Noisy pivots (CDN nameservers, common mail includes) never add a domain on their own
+- [ ] Name-scheme candidates are kept only when they share a fingerprint
+- [ ] Entity facts cite the page they came from; conflicting operator names are dated, not merged
+- [ ] Two signals from one vendor account are counted once
+- [ ] Every cluster member has a label and the matrix shows why
+- [ ] Loop ran until a full pass added nothing, or the stop reason is stated
+- [ ] Verdict is ≤3 sentences; no "owned by" without an entity citation
+- [ ] Outliers checked and rejected are listed with the reason

package/skills/payment/similar-domain/references/entities.md

@@ -0,0 +1,58 @@
+# Entities
+
+Step 4 names and dates the cluster. It runs after at least one brand name
+is known and after the technical links exist; it explains the cluster, it
+does not replace the evidence.
+
+## What to collect per brand
+
+| Fact | Where it usually is |
+|---|---|
+| Legal operator name and company number | Site footer, terms and conditions, "about" page, review aggregators |
+| Licence authority and number | Footer seal, validator link, regulator register |
+| Registered address | Terms page, regulator register |
+| Launch year and relaunches | Review aggregators, archives, certificate history |
+| Affiliate program | Footer "Affiliates" link, affiliate directories |
+| Platform vendor | Footer, script hosts, review sites |
+| Previous operators | Older reviews, forum threads, archive snapshots |
+| Complaint patterns | Review aggregators, complaint forums |
+
+Record each fact with its page and the date the page was written or
+captured. Review aggregators disagree with each other because operators
+migrate; keep every version with its date rather than picking one.
+
+## Entity pivots
+
+| Have | Reverse into | Yields |
+|---|---|---|
+| Operator name | Aggregator "owner" pages, licence register, web search of terms-page text | Brand list under that operator |
+| Licence number | Regulator register | Every licensed domain, including ones with no technical link yet |
+| Affiliate program | Affiliate directories and forums | Brands marketed together |
+| Address | Web search | Other entities at the address; treat corporate-service addresses as noise |
+| Platform vendor | Vendor's client list, review sites | Vendor-level neighbours; filter, do not add |
+| Previous operator | Same as operator name | The migration path (for example Curaçao entity → transitional entity → Anjouan entity) |
+
+## Migration patterns worth expecting
+
+Offshore operators reorganise often. Common shapes:
+
+- **Entity swap, same platform** — the brand keeps its template and
+  tokens; only the footer entity and licence change. Technical evidence
+  stays continuous; corporate evidence shows a break.
+- **Brand acquisition** — an old, once-reputable domain is bought and
+  relaunched on a new operator's platform. Registration date is old;
+  everything else matches the new cluster. Weight the technical evidence.
+- **Mirror farms** — numbered or hyphenated domains registered in batches,
+  each redirecting or serving the parent brand. They inherit every
+  fingerprint and are usually Confirmed on the first pass.
+- **White-label tenants** — several unrelated operators on one vendor
+  platform share vendor-level fingerprints but not operator-level ones.
+  This is the main source of false clusters.
+
+## Adding a domain from entity evidence alone
+
+Allowed only when the source is authoritative for domain membership: a
+regulator's licence register, or the operator's own terms page listing its
+domains. Label such domains Probable until a technical fingerprint
+confirms them. Aggregator sister-site lists are hypotheses to test, not
+grounds for membership.