@vegastack/vegafactory 0.19.0

package/skill/skill-maintainer/refresh/REFRESH.md

@@ -0,0 +1,40 @@
+# Refresh contract — skill-maintainer
+
+Instructions for the scheduled refresh agent (and any human running a manual refresh). This file, together with `sources.json`, is the complete freshness contract for this skill.
+
+## What this skill claims
+
+- **Durable content** (`SKILL.md` workflows and operating rules, `references/release-ops.md`): repo process, elaborating `.vegastack/dev.md` — the refresh agent NEVER edits these. If the process changes, that is a normal human PR, not a refresh.
+- **Volatile standards claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
+- **Volatile layer** (the only file the agent edits freely): `refresh/sources.json` — the source registry and staleness snapshot (checksums, retrieval times).
+
+## How to refresh
+
+The deterministic runner is repo-shared, hosted at `tooling/refresh/`. Run from the repo root:
+
+1. **Deterministic pass first** (no LLM judgment):
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/repo-tooling/skill-maintainer/refresh/sources.json`
+   drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. All four sources here are critical.
+2. **Accept verified changes** in the same code path:
+   `node tooling/refresh/refresh-evidence.mjs --registry skills/repo-tooling/skill-maintainer/refresh/sources.json --accept-baselines`
+   This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run. Baselines are runner-seeded; when a new source is added or a verified change is accepted, this accept-baselines invocation is the only sanctioned way to update them.
+3. **Semantic verification** for every source the deterministic pass flagged: read the changed page (fetch the registry URL), decide whether any `<!-- source: X -->` marked sentence in `references/standards.md` (or the mirrored SKILL.md hard-limits row) is now wrong, and propose the minimal edit. Unlike version-pin registries, checksum drift here is presumed meaningful until a human reads the diff — these pages define the standards themselves. Editorial churn may be accepted silently only after that read.
+4. **One standing refresh PR**, branch `refresh/weekly`, force-updated on every run (never stacked duplicates; the weekly workflow .github/workflows/refresh.yml maintains it). PR body lists: each changed source, old→new checksum, links to the evidence, and which marked sentences changed and why. A maintainer review is mandatory before merge.
+5. Changes to durable content, workflows, tests, or anything outside `refresh/` and marked sentences are out of scope for a refresh PR — CI enforces this (refresh-guard workflow).
+
+## Cadence and thresholds
+
+Weekly scheduled run. Every `thresholdDays` in `sources.json` is ≥ 14 (2× cadence) so one missed run never breaches a threshold.
+
+## What counts as drift worth a PR
+
+- Any text-scope checksum change on any of the four sources → read the page; if a discovery path, frontmatter rule, numeric budget, or install surface changed, propose the marked-sentence edit and flag it prominently — downstream, every skill in `skills/` may need re-checking against the new standard (that re-check is a separate human task, never part of the refresh PR).
+- A source page moves to an UNVERIFIED area (e.g. a documented path disappears) → move the claim into the UNVERIFIED register in `references/standards.md` rather than asserting the old fact.
+- A critical source is unavailable or a redirect leaves the approved host set → investigate immediately; host changes require a deliberate `approvedHosts` update in the shared runner (out of refresh-PR scope — open an issue).
+
+## Never
+
+- Never edit unmarked sentences, workflows, or `references/release-ops.md`.
+- Never hand-write checksum/version/timestamp values.
+- Never merge a standards change without human review — this registry has no auto-acceptable semantic drift.
+- Never archive third-party documentation bodies in this repo (claim metadata, URLs, hashes, and concise excerpts only).

package/skill/skill-maintainer/refresh/sources.json

@@ -0,0 +1,103 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "criticalTopics": [
+      "skills-standard"
+    ],
+    "defaultChecksumScope": "html-text-v1",
+    "offline": "Use cached metadata only; fail closed when a critical entry is missing or older than thresholdDays.",
+    "drift": "All four sources are the compliance basis for this skill: any drift requires reading the changed page and a human-reviewed PR updating the marked sentences in references/standards.md (and the mirrored hard-limits table in SKILL.md); never auto-apply.",
+    "copyright": "Store claim metadata, URLs, hashes, headers, and concise excerpts only; never archive whole third-party documentation corpora.",
+    "cadence": "weekly automated refresh; thresholdDays must be >= 14 (2x cadence) so a single missed run never breaches a threshold"
+  },
+  "sources": [
+    {
+      "id": "AGENTSKILLS-SPEC",
+      "service": "agentskills.io specification",
+      "kind": "official-spec",
+      "stability": "open-standard",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://agentskills.io/specification"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "f2c589e5fd5e4b4684fdf6567262c24dea6a3b14eca795ab1dca3c4b7a3e1eea",
+      "retrievedAt": "2026-08-29T05:57:04.887Z"
+    },
+    {
+      "id": "CLAUDE-CODE-SKILLS",
+      "service": "Claude Code skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "92f9993b6c2cb79be4ecf3d2785c310978d4daf308df6a0d4d076845028b170b",
+      "retrievedAt": "2026-08-29T05:57:04.887Z"
+    },
+    {
+      "id": "CODEX-SKILLS",
+      "service": "Codex skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://developers.openai.com/codex/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "e6ede44b27e6195c1920bdfb2f3f15e548f3ba34feeffad3a0cb23c54a0f63b9",
+      "retrievedAt": "2026-08-29T05:57:04.887Z"
+    },
+    {
+      "id": "HERMES-SKILLS",
+      "service": "Hermes Agent skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://hermes-agent.nousresearch.com/docs/user-guide/features/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "d3cbea81c2c03c6ab480848c79d75d4914109898509344b774428579cc642223",
+      "retrievedAt": "2026-08-29T05:57:04.887Z"
+    }
+  ]
+}

package/skill/skill-scan/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: skill-scan
+description: Scan agent skills for prompt-injection, rogue-agent, and supply-chain findings with NVIDIA SkillSpector, and hold the suppression baseline that records which findings are accepted and why. Use when asked to scan or vet skills, to judge whether a third-party or downloaded skill is safe to install, when a scan blocks and its findings need triage, when a file edit expires a coverage acceptance and it needs re-adjudicating, or when dev-implement's Verify gate or a project's Ship guard runs the scan. Not for reviewing a code diff against its brief and plan (dev-review, whose security axis consumes this scan's report), authoring or auditing a skill (skillify), or repo release standards (skill-maintainer).
+---
+
+# skill-scan
+
+An installed skill runs with your agent's authority, so a skill you did not read is a program you did not read. This guard scans skills — yours and strangers' — with NVIDIA SkillSpector, and holds the record of every finding anyone decided to accept.
+
+Nearest neighbors: `dev-implement` runs this at its Verify gate and a project's `## Ship` runbook runs it before publishing; `dev-review`'s Security axis consumes the report this produces and triages what sits below the blocking bar; `skillify` audits a skill's completeness, which is a different question entirely.
+
+## Running it
+
+Run from the project root, with `<path-to-skill-scan>` standing for wherever this skill is installed:
+
+```sh
+node <path-to-skill-scan>/scripts/skill-scan.mjs --json           # the gate: reads the knobs and the project baseline
+node <path-to-skill-scan>/scripts/skill-scan.mjs --llm            # adds the semantic pass — advisory, never a gate
+node <path-to-skill-scan>/scripts/skill-scan.mjs --root ~/Downloads/some-skill   # vet a skill you did not write
+node <path-to-skill-scan>/scripts/skill-scan.mjs --no-provision   # this run installs and upgrades nothing
+```
+
+**Exit codes are the contract: 0 pass (or skipped) · 1 pass-with-warnings · 2 blocked.** Exit 2 stops the hand-back — fix the finding, or take it to the operator for a justified baseline entry. Widening a rule to reach green is the one move this guard exists to prevent.
+
+## The two knobs, both in `.vegastack/dev.md`
+
+- `skill-scan:` names the root to scan — in a repo that builds a bundle, the **built** one, because that is what the world installs. `none` (or no line) turns the scan off and the guard says plainly that it skipped. A profile it cannot *read* is a different answer and blocks, so the gate can never disable itself by being run from the wrong directory.
+- `skillspector-update:` takes `off | notify | auto`, and an absent line reads as `auto`: `auto` installs SkillSpector when absent and upgrades it before every scan (any failure falls back to the installed copy and the scan continues), `notify` reports the newest release and changes nothing, `off` makes no network call. The mode is read from the profile on **every** run, `--root` included — `--root` chooses what to scan, never whether this machine may be written to. `--no-provision` opts a single run out.
+
+The guard finds the CLI through whatever channel installed it — uv, Homebrew, or pipx — and runs it by absolute path, so it works when the agent's shell `PATH` differs from the operator's. Only a scanner no channel reports *and* that is not on `PATH` refuses, and that message names every remedy.
+
+Discovery reads exactly two levels: a skill sitting directly under the scan root, and a skill one group deep. Anything else holding a skill manifest blocks rather than being skipped — buried deeper, dot-prefixed, or behind a symlink, which is never followed. An unscanned skill nobody mentions looks exactly like a clean one.
+
+## The baseline — three sections, and the discipline behind them
+
+`.vegastack/skillspector-baseline.json` is applied by convention when no `--root` is given. An explicit `--root` never inherits it: a rule written for your own content should not silence a finding in someone else's skill.
+
+| Section | Accepts | Keyed by |
+|---|---|---|
+| `rules` | a finding class this project has judged and accepted | literal `id` and `path` |
+| `fingerprints` | one specific occurrence | content hash |
+| `coverage` | a file the scanner could not finish reading | `skill` + `file` + `sha256` |
+
+`coverage` is ours rather than SkillSpector's, whose baseline suppresses findings only and cannot express "I could not finish reading this" — which any skill shipping ordinary JavaScript will hit. An acceptance covers exactly the file it names and exactly the bytes it names: **editing the file expires its acceptance**, and the fix is to re-adjudicate — confirm the reason code and degraded-analyzer count still hold, record the fresh digest, and append one sentence saying what changed — never to widen the entry.
+
+Two rules the guard enforces rather than trusts:
+
+- **Matchers are literal.** `*`, `?`, `[` and `]` are rejected. A single `{"id": "*"}` once silenced every finding while the run reported success, and a fix that rejected `*` was bypassed by `?*` immediately. Naming the file is the only "as narrow as its cause" a guard can check.
+- **Every entry carries a `reason` with a "Still flag if:" clause** — the same discipline as `dev-review`'s known-patterns file. A suppression with no exception clause is a blind spot, and a rule scoped `id:` with no `path:` is a repo-wide one.
+
+It blocks on any unsuppressed HIGH or CRITICAL finding and never on the aggregate risk score, which is inflated by documentation of the very mechanics being scanned and deflated by unrelated suppressions. A degraded scan blocks too: a run whose analyzer failed reports a *higher* score with fewer filtered findings, so its silence proves nothing. An upgrade that changed anything is reported before the findings, because a new finding after an upgrade is the tool having learned something.
+
+## Vetting a skill you did not write
+
+Point `--root` at the directory before it reaches your agent. The report carries each finding's rule, severity, and `file:line`, plus every entry the baseline suppressed, so the judgement is traceable rather than a score taken on trust. Treat a hit as a candidate finding, not a verdict — and never downgrade an unexplained HIGH or CRITICAL on the strength of who published it.
+
+## A scan with no issue attached
+
+A standalone scan, or the pre-publish guard in a project's `## Ship` runbook, has no review comment to land in, so its findings go to `dev-intake` as a `risky` issue — a finding posted somewhere convenient is a finding nobody owns. Offer the operator one `risky` issue whose brief carries the findings, their locations, and what is known about each cause; intake's questions, scope call, and approval follow.

package/skill/skill-scan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "skill-scan"
+  short_description: "Scan and vet agent skills for vulnerabilities"
+  default_prompt: "Use $skill-scan to scan this project's skills and triage the findings."

package/skill/skill-scan/refresh/REFRESH.md

@@ -0,0 +1,18 @@
+# Refresh contract — skill-scan
+
+The scan discipline itself (exit codes, the baseline's three sections, the literal-matcher rule, the "Still flag if:" clause) asserts nothing that can go stale. What is volatile is `scripts/lib/skillspector.mjs`, which parses the output of third-party commands and calls a third-party API — the six sources below.
+
+What the registry tracks, and why each one is load-bearing rather than decorative: every parser below fails **silently** if its upstream surface changes — returning "not installed", which the guard reports as a missing scanner instead of a parsing bug. That silence is the whole reason these are registered.
+
+| Source | The claim it holds up | Breaks how |
+|---|---|---|
+| `SS-INSTALL` | `uv tool install git+https://github.com/NVIDIA/skillspector.git` is upstream's documented install, and the package is not on PyPI | the install command installs nothing, or the wrong thing |
+| `SS-VERSION-OUTPUT` | `skillspector --version` prints `SkillSpector v<x.y.z>` on **stdout**, warnings on stderr | version reporting goes null; the baseline-pin warning stops firing |
+| `SS-RELEASES-API` | the GitHub releases endpoint shape, and its 60-request/hour unauthenticated limit | `notify` silently reports nothing |
+| `UV-TOOL-LIST` | `uv tool list --show-paths` prints `- skillspector (/abs/path)` | uv-installed scanners read as absent |
+| `BREW-PREFIX` | `brew list --versions` exits non-zero when absent, while `brew --prefix` exits **0 with a path for any known formula** whether or not it is installed | brew detection returns a path that does not exist |
+| `PIPX-LIST` | `pipx list --short` exits 0 even with nothing installed, so its output must be parsed | pipx-installed scanners read as absent, or absence reads as present |
+
+These six moved here from `dev-review` on 03-09-2026 with issue #113, when the guard became its own skill; the registry entries are unchanged, and their `affected` paths were already skill-relative.
+
+Drift in any of them means reading the changed surface and updating both the parser and its dated comment in the same reviewed PR — never auto-applying. The parsers each have a unit test pinning the exact output shape, so a corrected parser has a failing test to satisfy.

package/skill/skill-scan/refresh/sources.json

@@ -0,0 +1,133 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "defaultChecksumScope": "html-text-v1",
+    "offline": "Use cached metadata only; fail closed when an entry is missing or older than thresholdDays.",
+    "drift": "Read the changed surface, then update the parser AND its dated comment in one reviewed PR; never auto-apply. Each parser has a unit test pinning the output shape.",
+    "copyright": "Store claim metadata, URLs, hashes and concise excerpts only; never archive third-party documentation.",
+    "cadence": "weekly scheduled refresh; thresholdDays must be >= 14 (2x cadence) so one missed run never breaches a threshold"
+  },
+  "sources": [
+    {
+      "id": "SS-INSTALL",
+      "service": "SkillSpector install instructions (uv; not on PyPI)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://github.com/NVIDIA/SkillSpector"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skillspector-install"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs",
+        "README.md"
+      ]
+    },
+    {
+      "id": "SS-VERSION-OUTPUT",
+      "service": "skillspector --version output shape (stdout vs stderr)",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://github.com/NVIDIA/SkillSpector"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skillspector-version"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs"
+      ]
+    },
+    {
+      "id": "SS-RELEASES-API",
+      "service": "GitHub releases endpoint shape and unauthenticated rate limit",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://docs.github.com/en/rest/releases/releases"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skillspector-releases"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs"
+      ]
+    },
+    {
+      "id": "UV-TOOL-LIST",
+      "service": "uv tool list --show-paths output shape",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://docs.astral.sh/uv/concepts/tools/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "channel-uv"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs"
+      ]
+    },
+    {
+      "id": "BREW-PREFIX",
+      "service": "brew list --versions vs brew --prefix exit semantics",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://docs.brew.sh/Manpage"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "channel-brew"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs"
+      ]
+    },
+    {
+      "id": "PIPX-LIST",
+      "service": "pipx list --short exit code and output",
+      "kind": "official-docs",
+      "stability": "vendor-docs",
+      "thresholdDays": 14,
+      "critical": false,
+      "urls": {
+        "primary": "https://pipx.pypa.io/stable/docs/"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "channel-pipx"
+      ],
+      "affected": [
+        "scripts/lib/skillspector.mjs"
+      ]
+    }
+  ]
+}

package/skill/skill-scan/scripts/lib/skillspector.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// Everything about the SkillSpector CLI itself — where it is, installing it,
+// upgrading it, reading its version. `skill-scan.mjs` keeps owning the scan and
+// the verdict and calls in here once, before scanning.
+//
+// Named for the tool, not for its role: this repo's own machinery is "skill
+// scan", and the third-party binary is always "skillspector" by its exact name,
+// so the generic word stays free (operator's rule, 01-09-2026).
+//
+// Every command runs through an injected `run`, and every path check through an
+// injected `exists`, so unit tests never install software or touch the disk.
+// Self-contained (ships with skill-scan; no cross-skill imports, no dependencies).
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Upstream's own documented quick install, verified 01-09-2026 against the
+// SkillSpector README, which documents uv and no other package manager. The git
+// URL is not optional: the package is NOT published to PyPI (HTTP 404), so a
+// bare `pip install skillspector` can never work.
+export const INSTALL_COMMAND = ['uv', ['tool', 'install', 'git+https://github.com/NVIDIA/skillspector.git']];
+
+// Per channel, in probe order. `detect` proves the tool is actually installed;
+// `locate` turns that into an absolute executable path.
+const UPGRADE = {
+  uv: ['uv', ['tool', 'upgrade', 'skillspector']],
+  brew: ['brew', ['upgrade', 'skillspector']],
+  pipx: ['pipx', ['upgrade', 'skillspector']],
+};
+
+// A command runner that never throws: a non-zero exit is data, not an
+// exception, because "brew is not installed here" is an ordinary answer to
+// "where is skillspector". stderr is folded into stdout so a failure message
+// survives for the report.
+// stdio mode for a discarded fd, hoisted out of quote-adjacency: SkillSpector reads the
+// bare word beside its own closing quote as a removal cue and fails closed on the whole
+// file (skill-maintainer's standards.md, known behaviours). Same value, same behaviour.
+const DISCARD = 'ignore';
+
+export function defaultRun(cmd, args, { timeoutMs = 300_000 } = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: [DISCARD, 'pipe', 'pipe'],
+      // `env` is passed explicitly, as skill-scan.mjs does: under Bun a mutated
+      // process.env is NOT inherited by execFileSync children.
+      env: { ...process.env },
+      timeout: timeoutMs,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return { ok: true, stdout };
+  } catch (error) {
+    const out = ((error.stdout?.toString() ?? '') + (error.stderr?.toString() ?? '')).trim();
+    return { ok: false, stdout: out || error.message || '' };
+  }
+}
+
+// `uv tool list --show-paths` prints one line per tool and one indented line per
+// executable it installed:
+//   skillspector v2.11.0 (/home/x/.local/share/uv/tools/skillspector)
+//   - skillspector (/home/x/.local/bin/skillspector)
+// The executable line is the one that matters — the first is the venv, which is
+// not runnable. Anchored on both sides so `skillspector-extra` cannot match.
+export function parseUvToolList(text) {
+  for (const line of String(text ?? '').split('\n')) {
+    const match = /^-\s+skillspector\s+\((.+)\)\s*$/.exec(line.trim());
+    if (match) return match[1];
+  }
+  return null;
+}
+
+// `pipx list --short` exits 0 whether or not anything is installed (verified
+// 01-09-2026 — it prints "nothing has been installed with pipx" and succeeds),
+// so the exit code proves nothing and the listing has to be read.
+export function parsePipxList(text) {
+  return String(text ?? '')
+    .split('\n')
+    .some((line) => /^skillspector(\s|$)/.test(line.trim()));
+}
+
+// Ask each channel where it put the executable, in order, and believe only a
+// path that is actually on disk.
+//
+// The existence check is not defensive padding: `brew --prefix <formula>` exits
+// 0 and prints a path for any formula it KNOWS, installed or not — verified
+// 01-09-2026, where it named /opt/homebrew/opt/skillspector while nothing was
+// installed there. Detection therefore runs `brew list --versions` first, and
+// the check below is the backstop for every channel.
+export function locateSkillspector({ run = defaultRun, exists = existsSync } = {}) {
+  const believe = (channel, path) => (path && exists(path) ? { channel, path } : null);
+
+  const uv = run('uv', ['tool', 'list', '--show-paths']);
+  if (uv.ok) {
+    const found = believe('uv', parseUvToolList(uv.stdout));
+    if (found) return found;
+  }
+
+  if (run('brew', ['list', '--versions', 'skillspector']).ok) {
+    const prefix = run('brew', ['--prefix', 'skillspector']);
+    if (prefix.ok && prefix.stdout.trim()) {
+      const found = believe('brew', join(prefix.stdout.trim(), 'bin', 'skillspector'));
+      if (found) return found;
+    }
+  }
+
+  const pipx = run('pipx', ['list', '--short']);
+  if (pipx.ok && parsePipxList(pipx.stdout)) {
+    const dir = run('pipx', ['environment', '--value', 'PIPX_BIN_DIR']);
+    if (dir.ok && dir.stdout.trim()) {
+      const found = believe('pipx', join(dir.stdout.trim(), 'skillspector'));
+      if (found) return found;
+    }
+  }
+
+  return null;
+}
+
+
+// Strip C0/C1 controls (ANSI escapes included) from anything a command printed:
+// this text reaches a terminal report, and package-manager output carries names
+// from outside the repo. Mirrors skill-scan.mjs's own `safe()`.
+function safe(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\u0000-\u001f\u007f-\u009f]/g, '?');
+}
+
+// `skillspector --version` prints "SkillSpector v2.11.0" on STDOUT while its
+// missing-API-key warnings go to stderr (verified 01-09-2026). `run` hands back
+// stdout alone on success, so the warnings can never contaminate the match.
+export function readVersion({ path, run = defaultRun }) {
+  const result = run(path, ['--version']);
+  if (!result.ok) return null;
+  const match = /SkillSpector\s+v?(\d+\.\d+\.\d+\S*)/i.exec(result.stdout);
+  return match ? match[1] : null;
+}
+
+// The lines a package manager reported moving. uv prints one `+ pkg==x` /
+// `- pkg==y` line per dependency it changed; anything else simply yields none.
+function changedLines(stdout) {
+  return String(stdout ?? '')
+    .split('\n')
+    .map((line) => safe(line.trim()))
+    .filter((line) => /^[+-]\s*\S/.test(line));
+}
+
+// Install when absent, upgrade when present — and never throw: a machine
+// without a network, without uv, or with a locked package manager must fall
+// back to whatever is already installed and let the scan proceed. Only a
+// SkillSpector that cannot be found at all blocks, and that is skill-scan's
+// call, not this function's.
+//
+// No version check runs first, deliberately. `uv tool upgrade` moves the whole
+// dependency tree while the version string can hold steady (verified
+// 01-09-2026: langsmith 0.11.2 -> 0.12.0 under an unchanged v2.11.0), so
+// comparing versions would report "current" about a tool that just changed.
+export function provisionSkillspector({ mode, located, run = defaultRun }) {
+  const idle = { action: 'none', before: null, after: null, changed: [], message: '' };
+
+  // `notify` reports; it never touches the machine. The release lookup that
+  // makes it useful belongs to the caller, which owns the network policy.
+  if (mode !== 'auto') return located ? { ...idle, before: readVersion({ path: located.path, run }) } : idle;
+
+  if (!located) {
+    const [cmd, args] = INSTALL_COMMAND;
+    const result = run(cmd, args);
+    if (!result.ok) {
+      return { ...idle, action: 'failed', message: safe(result.stdout), changed: changedLines(result.stdout) };
+    }
+    // `after` stays null: reading it needs the path, and only a fresh locate
+    // knows where the install landed. The caller re-locates and fills it in.
+    return { action: 'installed', before: null, after: null, changed: changedLines(result.stdout), message: '' };
+  }
+
+  const upgrade = UPGRADE[located.channel];
+  if (!upgrade) {
+    return { ...idle, message: `no upgrade command is known for the ${safe(String(located.channel))} channel` };
+  }
+
+  const before = readVersion({ path: located.path, run });
+  const result = run(upgrade[0], upgrade[1]);
+  if (!result.ok) {
+    return { action: 'failed', before, after: before, changed: [], message: safe(result.stdout) };
+  }
+  return {
+    action: 'upgraded',
+    before,
+    after: readVersion({ path: located.path, run }),
+    changed: changedLines(result.stdout),
+    message: '',
+  };
+}
+
+
+// Upstream's releases feed. Unauthenticated and rate-limited to 60 requests an
+// hour per IP (verified 01-09-2026), which `notify` stays far inside because it
+// asks once per guard run and only in that mode.
+export const RELEASES_URL = 'https://api.github.com/repos/NVIDIA/SkillSpector/releases/latest';
+
+async function fetchReleaseJson(url) {
+  // GitHub rejects requests without a User-Agent.
+  const response = await fetch(url, {
+    headers: { accept: 'application/vnd.github+json', 'user-agent': 'vegastack-skill-scan' },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json();
+}
+
+// The newest published release, or null. EVERY failure path is null and never a
+// throw: `notify` is a courtesy line in a report, and a guard must not turn a
+// flaky network into a verdict. A tag that is not a plain version (a nightly, a
+// moved pointer) is rejected rather than reported as a version.
+export async function latestRelease({ fetchJson = fetchReleaseJson, url = RELEASES_URL } = {}) {
+  let body;
+  try {
+    body = await fetchJson(url);
+  } catch {
+    return null;
+  }
+  if (!body || typeof body !== 'object') return null;
+  const tag = typeof body.tag_name === 'string' ? body.tag_name.trim() : '';
+  const match = /^v?(\d+\.\d+\.\d+\S*)$/.exec(tag);
+  return match ? match[1] : null;
+}
+
+export const UPGRADE_COMMANDS = UPGRADE;