@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/golden-path/references/contract.md

@@ -0,0 +1,239 @@
+# The golden-path contract (`golden-paths.json`, version 3)
+
+One JSON file per app, next to its `package.json`. The engine validates it, selects
+from it, drives it, and renders `GOLDEN_PATHS.md` and the workflow from it.
+Example: [../assets/golden-paths.example.json](../assets/golden-paths.example.json).
+
+```json
+{
+  "version": 3,
+  "profiles": { "pr-local": { "gate": "pull-request", "environment": "local", "endpoint": "local", "mutationPolicy": "isolated-writes" } },
+  "setup": { "boot": "pnpm start", "baseUrl": "http://127.0.0.1:3000", "journeys": "e2e/journeys" },
+  "ci": { "queue": "mergify", "packageManager": "pnpm" },
+  "paths": [ { "id": "health", "title": "The app is serving", "surface": "api", "start": "GET /api/health", "expect": { "status": 200 }, "observable": "200 ok", "profiles": ["pr-local"] } ]
+}
+```
+
+Any value that starts with `TODO` fails validation, so a scaffold or a migration
+never generates a workflow before a person fills it in.
+
+## What earns a path
+
+A path belongs only if **its failure alone would block a release**. Common shapes:
+get in (sign in, sign up), the core action the product exists for (checkout, publish,
+submit a case), it's up (health), and anything touching money or irreversible state.
+There is no target count; if the list grows toward dozens, the rest belongs in
+`e2e-test`'s journey suite. Candidates come from the critical E2E journeys, the
+state changes of the core entities, ADRs that name a load-bearing flow, and
+`suggest` over the surface inventory, in that order. A person promotes them.
+
+## `paths[]`
+
+| Field | Required | Meaning |
+|---|---|---|
+| `id` | yes | Lowercase slug, unique; results are keyed by it |
+| `title` | yes | One line on what the user achieves, under 80 characters; the view shows it |
+| `surface` | yes | `browser`, `api`, or `cli` |
+| `journey` | browser | The `@covers` id of the spec tagged `@golden-path` that drives it. The spec owns the steps and assertions |
+| `config` | browser, optional | A Playwright config file for this path, when it needs one other than the default; paths sharing a config run in one invocation |
+| `start` | api | One request to the target, `"GET /api/health"`. Use `request` for anything more. A path that must call another service is a cli path (`curl ...`), since api paths never leave the target's origin |
+| `request` | api, optional | `{ "method", "path", "headers"?, "body"? }`, sent to the target. When both are set, `run` sends `request` and the view shows it |
+| `command` | cli | Shell command, run in the app directory |
+| `expect` | api/cli, recommended | Machine check. api: `status` (number or list; default any 2xx; redirects are not followed), `bodyIncludes` (string or list), `json` (an object the response must contain), `jsonNonEmpty` (dotted paths that must hold a non-empty value, like `keys`), `headers` (`{ "Content-Type": "text/markdown" }`: each value must include the text). cli: `exitCode` (default 0), `stdoutIncludes` (stdout only, not stderr). A check `expect` cannot state belongs in a repo test, or a cli path that runs one |
+| `observable` | api/cli | The fact that proves it worked, for people; under 300 characters |
+| `intent` | no | Extra note for a browser path; documentation only |
+| `documentation` | no | Human-readable localized journey description; see [documentation](#documentation). It does not replace the executable fields or tagged spec |
+| `nonWriting` | no | For a `POST`/`PUT`/`PATCH`/`DELETE` path with `mutates: false` in a dev or prod profile: why the server cannot write, such as a probe that must be refused (`"the candidate answers 404 before parsing"`). Without it `validate` rejects the path |
+| `mutates` | no | Boolean. `true` when the path writes data that would outlive the run in a shared environment (dev or prod). A path that writes only the run's throwaway local store, like a migration against the per-run database, can stay `false` if it is declared in local profiles only |
+| `tenant` | when `mutates` | Synthetic tenant, `e2e-` prefixed, listed in `setup.tenants`. A label for selection and cleanup: `run` sends nothing for it, so put the tenant in `request.headers` or `request.body` the way the app expects |
+| `cleanup` | when `mutates` | How its writes are removed |
+| `profiles` | yes | The profiles this path must pass in |
+
+Other keys are kept and ignored, so a repo can carry its own annotations. Keys
+starting with `_` (top level or on a path) are never read at all: park a path that
+has no driver yet under `_pendingPaths` instead of deleting it.
+
+## `documentation`
+
+Optional on a path. Keep the executable contract unchanged: `id`, `journey`,
+`expect`, profiles, mutation rules, and spec tags retain their existing meanings
+and requirements. Documentation describes what the existing spec proves; it does
+not supply instructions to `run`.
+
+```json
+{
+  "reference": "GP-IDENTITY-LOGIN",
+  "title": { "en": "Sign in", "zh": "登录" },
+  "group": { "en": "Identity", "zh": "身份", "order": 10 },
+  "precondition": { "en": "A returning user is signed out", "zh": "已有用户尚未登录" },
+  "summary": {
+    "route": { "en": "Sign in → Dashboard", "zh": "登录 → 仪表盘" },
+    "outcome": { "en": "The user's dashboard is visible", "zh": "用户的仪表盘可见" }
+  },
+  "steps": [
+    {
+      "action": { "en": "Submit valid credentials", "zh": "提交有效凭据" },
+      "expected": { "en": "The dashboard opens for this user", "zh": "打开该用户的仪表盘" }
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `reference` | Optional explicit stable human reference, matching `GP-[A-Z0-9]+(?:-[A-Z0-9]+)*`, unique across all paths, including services. For example `GP-IDENTITY-LOGIN`. Never derive it from list position, category, or title; preserve it through insertion, reorder, regrouping, and display-title changes |
+| `title` | Optional `{ "en", "zh"? }`; overrides the display title, not the executable `id`. Absent: use the path's existing title |
+| `group` | Optional `{ "en", "zh"?, "order"? }` for browser journey grouping; `order` is a nonnegative integer when present. Service checks remain a separate appendix |
+| `precondition` | Optional `{ "en", "zh"? }` describing the starting state |
+| `summary` | Optional object with both `route` and `outcome`, each `{ "en", "zh"? }`. Use `→` between route stops. When Chinese is supplied, pair the Chinese route and outcome |
+| `steps` | Nonempty list of `{ "action": { "en", "zh"? }, "expected": { "en", "zh"? } }`. Preserve the full original actions and expectations, not only the summary |
+
+Each localized value needs nonempty English and, when present, nonempty Chinese.
+Keep bilingual copy paired: when the title, precondition, or steps supply Chinese,
+provide Chinese for every step's action and expected result. `validate` rejects
+malformed documentation and malformed or duplicate references.
+
+`id` remains the executable identity used by selection, results, and spec tags;
+`reference` is only the stable human label. In the documented view, headings are
+`### GP-IDENTITY-LOGIN: Sign in`. Contents entries show
+`GP-IDENTITY-LOGIN: Sign in / 登录` and link to `#golden-path-sign-in`.
+Anchors always remain `#golden-path-${id}`. Without `reference`, both the heading
+and Contents use the existing path `id`, never a positional `GP-01` number.
+
+The generated view groups browser journeys separately from a service-check
+appendix. English/Chinese titles and copy appear together. A path with `summary`
+shows its route and outcome outside a closed
+`<details><summary>Full steps / 完整步骤</summary>` containing the precondition,
+full original steps, and executable verification. English-only copy uses
+`Full steps`. A path without `summary` stays expanded. Documentation text is
+HTML- and Markdown-escaped so literal markup cannot change the Contents target,
+formatting, or disclosure state. Malformed documentation (including duplicate
+references) blocks rendering with field-level diagnostics; fix it before running
+`init --write` or `render --write`. An entirely
+undocumented contract retains the legacy path table; adding documentation does
+not require converting every other path.
+
+## `profiles`
+
+A profile names one gate. Selection is a pure function of the profile name and the
+contract, so `run` and `verdict` always agree on the set.
+
+| Name | gate | environment / endpoint | mutationPolicy | Run by |
+|---|---|---|---|---|
+| `pr-local` | `pull-request` | local / local | `isolated-writes` | generated workflow, on PRs |
+| `queue-local` | `merge-queue` | local / local | `isolated-writes` | generated workflow, in the queue |
+| `dev-active` | `trunk-integration` | dev / active | `synthetic-tenant` | the dev deploy pipeline |
+| `prod-preview` | `pre-promotion` | prod / preview (0% traffic) | `read-only` | the release lane, before promotion |
+| `prod-active` | `post-promotion` | prod / active | `read-only` | the release lane, after promotion |
+
+- Each gate fixes its environment and endpoint; other pairings fail.
+- Production is `read-only`: every `mutates: true` path is skipped, tenant or not.
+  `synthetic-tenant` runs a writing path only with a tenant. `isolated-writes` is
+  local only.
+- These five names are reserved: other lanes select them by name, so each must keep
+  its gate. Drop the ones an app does not use; add your own names for other needs.
+- Optional per profile: `prerequisites` (strings), `evidencePolicy` (string), and
+  `forbidEnv` (variable names `run` refuses to see set, such as a test-login secret
+  on a production run).
+- `run` binds targets: a `local` profile drives only `localhost`, `127.0.0.1`, or
+  `[::1]`; any other profile drives only `https://`.
+- A deploy lane that must not write even in dev declares its own profile, for
+  example `"dev-readonly": { "gate": "trunk-integration", "environment": "dev",
+  "endpoint": "active", "mutationPolicy": "synthetic-tenant", ... }` declared only
+  on read-only paths; there is no `--read-only` flag.
+
+A profile that selects nothing yields EMPTY, never ALIVE.
+
+`--surfaces api,cli` narrows `plan`, `run`, and `verdict` to some surfaces, for a
+deploy step whose runner has no browser. `run` records the narrowing; `verdict`
+uses it and refuses a different one. A narrowed ALIVE covers only those surfaces;
+the deploy lane that skips browser paths owes them elsewhere. `--paths id,id` does
+the same for a list of path ids, so a sharded job runs and judges its own share.
+
+## `setup`
+
+Everything a run needs before it can drive a path. The workflow is generated from it.
+
+| Field | Meaning |
+|---|---|
+| `boot` | **Required.** One shell command that starts the app and keeps running |
+| `baseUrl` | Where the booted app listens; default `http://127.0.0.1:3000` |
+| `healthPath` | Path the workflow waits on before driving; default: the first GET api path that looks like a health check, else `/` |
+| `install` | Dependency install; default from the package manager (`pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`), or a plain install when `ci.cache` is `false` |
+| `build` | Build step before boot |
+| `seed` | Migrations and seed data |
+| `journeys` | Directory of the tagged browser specs, relative to the app |
+| `database` | `{ "engine": "postgres", "version"?: "17", "urlEnv"?: "DATABASE_URL" }`: a throwaway Postgres on tmpfs per run |
+| `env` | Literal, non-secret values for the local build: `{ "E2E_AUTH_BYPASS": "1" }`. Applied to local profiles and the workflow only; a deployed target keeps the runner's own environment |
+| `secrets.generate` | Names given a random masked value per run (auth secrets, test-route secrets) |
+| `secrets.fromCi` | Names read from the repository's CI secrets |
+| `browser` | `{ "command"?: "pnpm exec playwright test", "install"?: "pnpm exec playwright install --with-deps chromium" }`. The command may be a wrapper script (for example one that runs Playwright in a container); the JSON report is written to `golden-path-playwright.json` in the app directory, so mount the app. `run` passes the spec files, `--reporter=list,json`, and `BASE_URL` / `PLAYWRIGHT_BASE_URL` set to the target. The repo's Playwright config must use that URL and reuse the running app: a `webServer` block needs `reuseExistingServer: true` in CI (or an env such as `PLAYWRIGHT_REUSE_EXISTING_SERVER` in `setup.env` that the config reads), or it starts a second server |
+| `attestation` | `{ "path": "/api/version", "field": "sha" }` (a dotted field like `build.sha` works): lets `run --expect-sha` refuse a target serving another commit. Both shas need 7+ hex characters |
+| `authBypass`, `fixtures` | Notes for people: where the test login and fixtures live |
+| `tenants` | Every synthetic tenant a path uses, `e2e-` prefixed |
+
+## `ci`
+
+| Field | Meaning |
+|---|---|
+| `enabled` | `false` to generate no workflow |
+| `queue` | `mergify` (runs `queue-local` on `mergify/merge-queue/**` pushes), `github` (`merge_group`), or `none` |
+| `packageManager` | `pnpm`, `npm`, or `yarn`; detected at init |
+| `node` | Node version; default `22` |
+| `runner` | `runs-on` label; default `ubuntu-latest`. The job assumes a GitHub-hosted-like runner: Docker for the Postgres `services` container and sudo for `playwright install --with-deps`. When the repo's runner breaks any of that (no Docker, no sudo, Playwright only in a container, sharded lanes), set `ci.enabled` to `false`, keep the repo's own job, and call `run` and `verdict` from it |
+| `timeoutMinutes` | Job timeout; default 20 |
+| `lockfile` | Repo-relative lockfile path, set by init when a monorepo app shares the workspace-root lockfile |
+| `cache` | `false` when the app has no lockfile: no dependency cache and a plain install. Init sets it; `validate` warns when a lockfile is needed and missing |
+
+Values that land in the workflow must be plain: `baseUrl` and paths are URL
+characters only, env and secret names are `A-Z0-9_`, `runner` is one line of labels,
+and the names the workflow sets itself (`GOLDEN_PATH_PROFILE`, `BASE_URL`, the
+database URL) cannot be declared. Commands (`boot`, `install`, `build`, `seed`,
+`browser`) are shell commands by design.
+
+An app in a monorepo gets its own `golden-paths-<app>.yml` and its own blocks in the
+repo-root `README.md` and `AGENTS.md`, linking to its app-local `GOLDEN_PATHS.md`,
+so several apps never overwrite each other. Init creates a missing README and
+preserves content outside the generated blocks. Setting `ci.enabled` to `false`
+and running `init --write` removes the generated workflow (only a file carrying the
+generated header).
+
+The workflow runs `pr-local` on pull requests and `queue-local` in the queue when
+those profiles exist. Its steps: checkout, Node, `check` (generated files current),
+per-run secrets, install, browsers, build, seed, boot, `wait` on the health path,
+`run`, `verdict` (the step that passes or fails the job), and on failure an upload
+of the server log, results, verdict, and Playwright report.
+
+## Results and verdict files
+
+`golden-path-results.json` is written by `run` as `{ profile, target, observedAt,
+results }`, where `results` is a list of `{ id, status, evidence?, note? }` and
+`status` is `pass`, `fail`, `blocked`, or `cannot-run`. `verdict` refuses an envelope
+from another profile or target. A bare list (results driven by hand) is accepted. A
+selected path with no result is `missing`.
+
+`golden-path-verdict.json` adds `verdict` (ALIVE, DEAD, CANNOT-RUN, EMPTY; any
+`fail` is DEAD), `ok`, the per-path `rows`, `broken`, `profile`, `target`,
+`noMutations` (true under a read-only profile), `engine`, `observedAt` (from the run),
+and `generatedAt` (when the verdict was computed). Release lanes must check
+`profile`, `target`, and the age of `observedAt` against their own release policy
+before trusting a verdict. Run the selected profile against the intended candidate
+when fresh evidence is required. Recomputing `verdict` updates `generatedAt`, not
+`observedAt`: it does not rerun a journey, refresh evidence, or prove a new build.
+
+## Spec tags
+
+```ts
+// @golden-path
+// @covers sign-in
+test('a returning user signs in and lands on the dashboard', async ({ page }) => { ... })
+```
+
+`validate` fails both ways: a browser path whose `journey` no tagged spec covers,
+and a tagged spec no path references. It also fails a tagged spec that covers more
+than one journey, because `run` executes whole files. The legacy `@smoke` tag is
+still read.
+
+`e2e-test` also tags specs with `@covers <surface-id>` (a route like `/cases/[id]`,
+or a prefixed id like `api:GET /cases`). Those stay: golden-path reads only ids that
+neither start with `/` nor carry a `kind:` prefix, so both tags live in one spec.

package/skills/engineering/golden-path/references/migration.md

@@ -0,0 +1,111 @@
+# Audit and migrate
+
+Move a repo from a `smoke.manifest.json`, `@smoke` tags, or its own smoke scripts to
+the golden-path contract and engine. Run everything from the repository root with
+this skill's engine: `node <skill-base-dir>/scripts/golden-path.mjs`.
+
+## 1. Audit
+
+`audit` reads the tree and prints one line per finding; it exits 1 while anything
+is left to migrate.
+
+| Finding | Meaning | Action |
+|---|---|---|
+| `legacy` | A `smoke.manifest.json` | `audit --write` converts it |
+| `drift` | It declares `pr-local`, but no workflow running smoke triggers on `pull_request` | The generated workflow runs it |
+| `engine` | A script that reads the smoke manifest or computes a verdict, or an older engine copy | Read it for repo-only features (step 4), then delete it |
+| `workflow` (PR or queue) | A job that runs smoke on pull requests or the merge queue | Replace it with the generated workflow; moving a required check is a merge-rule change, ask first |
+| `workflow` (deploy) | A smoke step after a deploy, on a schedule, or in `cloudbuild.yaml` | Keep the step; call `run` then `verdict` with the deployed profile, `--target`, and `--surfaces` when that runner has no browser |
+| `workflow` (validate only) | A step that only validates the old manifest | Switch it to `validate`, or drop it: the generated workflow runs `check` |
+| `workflow` (manual) | A `workflow_dispatch`-only job | Repoint it or leave it |
+| `tags` | Specs tagged `@smoke` | Still read. Retag to `@golden-path` only after the old scripts that read `@smoke` are gone |
+
+Audit judges a CI file by its commands and triggers, not by comments. Treat its
+lines as leads: confirm each before deleting anything.
+
+`audit --json` prints the same as data.
+
+## 2. Convert
+
+`audit --write` converts each legacy manifest into `golden-paths.json` in the same
+directory, then runs init there: engine copy, `GOLDEN_PATHS.md`, repo-root `README.md`
+and `AGENTS.md` pointers, and `.gitignore` entries. The old manifest stays unless you pass
+`--remove-legacy`; remove it once no workflow or script reads it.
+
+What the conversion does:
+
+- sets `version: 3`; keeps `profiles`, adding the standard five when there were none
+- strips the `@smoke` prefix from `journey`
+- moves the legacy `setup.env` name list into `setup.secrets.fromCi`
+- sets `ci.queue` from `.mergify.yml`, and `ci.packageManager` from the lockfile
+- collects every path `tenant` into `setup.tenants`
+- keeps unknown keys (for example `evidenceClass`) untouched
+
+## 3. Finish by hand
+
+The conversion prints "needs a person" lines and leaves `TODO:` placeholders, which
+fail `validate`, so no workflow is generated until each is resolved:
+
+- **`setup.boot`:** older manifests often hold prose. Write the one command that
+  starts the app.
+- **`title`:** taken from the first sentence of `intent` or `observable`, or from the
+  spec's test name when the spec holds one test, if it fits under 80 characters;
+  otherwise a placeholder with the longer text as a hint.
+- **`cleanup`:** required for each path that writes data. A path that writes only
+  the run's throwaway local database and runs in local profiles only can be
+  `mutates: false` instead ([contract.md](contract.md#paths)); a path that writes in
+  dev needs a tenant and a real cleanup.
+- **Paths that call another service** (a remote API, a data service): api paths
+  never leave the target's origin, so make them cli paths that call the service
+  (`curl ...` or the repo's existing script).
+- **A spec that needs its own Playwright config:** set `config` on that path.
+- **A spec that covers two journeys:** split it, one journey per file.
+- **`observable` over 300 characters:** keep the proof, and move setup, seeding, and
+  cleanup detail into the spec or `setup`.
+- **An api `start` with several requests:** split it into separate paths, or set
+  `request` for the one that proves the flow.
+- **`expect`:** add it to every api and cli path; without it a run checks only for a
+  2xx response or exit 0.
+- **`setup`:** add `install`, `build`, `seed`, `database`, `env`, and
+  `secrets.generate` for what a local run needs; the workflow is built from them.
+  Sort `secrets.fromCi` into real CI secrets, per-run generated secrets, and literal
+  `env` values. Make the Playwright config reuse the running app
+  ([contract.md](contract.md#setup)).
+- **Runner and triggers:** the generated job assumes a GitHub-hosted runner and runs
+  `pr-local` on pull requests. If the repo ran smoke only in the queue on purpose,
+  drop `pr-local`; if it needs a self-hosted runner without Docker, keep its own job
+  and call `run` and `verdict` from it.
+
+Then `validate`, and `init --write` to generate the workflow.
+
+Before deleting anything, grep the repo, its tests included, for the old names:
+`smoke.manifest.json`, the `smoke:*` package scripts, and Cloud Build step ids. Repo
+tests often pin them.
+
+## 4. Retire the old setup
+
+<!-- skill-script-path: consumer-copy -->
+
+- **Forked engines.** List what the repo's script does that the engine does not,
+  and decide per feature: express it in the contract, keep a small repo script
+  around `run`/`verdict`, or drop it. Delete the fork once nothing calls it.
+- **Hand-built PR and queue jobs.** Delete them once the generated workflow runs.
+  Moving a required check to the new job name is a merge-rule change: ask first.
+- **Deploy-time steps.** Replace their smoke call with:
+  ```bash
+  node scripts/golden-paths/golden-path.mjs run --profile dev-active --target "$URL" --expect-sha "$SHA"
+  node scripts/golden-paths/golden-path.mjs verdict --profile dev-active --target "$URL"
+  ```
+- **Duplicate spec lists.** A `package.json` script or CI matrix that lists the
+  smoke specs by hand is replaced by `run`, which finds specs by tag.
+- **Committed run output.** Delete run output committed by accident (results and
+  verdict files beside the app); keep historical evidence a doc links to. Init adds
+  the run output to `.gitignore`.
+- **Safety guards in the old engine.** Map them: loopback-only local runs and
+  https-only deployed runs are built in; credential refusal is a profile's
+  `forbidEnv`; a read-only deploy lane is its own profile
+  ([contract.md](contract.md#profiles)). Anything else stays in a small repo script
+  around `run` and `verdict`.
+
+Deliver the migration as one change: contract, engine, generated files, and the
+retired pieces.

package/skills/engineering/golden-path/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }