@vegastack/skills 0.16.1 → 0.17.0

package/README.md

@@ -2,17 +2,25 @@
 
 Installer for VegaStack Agent Skills — a family of self-contained skills for Claude Code, Codex, and Hermes, shipped in one integrity-checked package.
 
+Install the whole dev workflow, once per machine:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+`--global` is the recommended install: the skills land in your home directory and are available in every project you open. Drop it for a project-local install when a repository should carry its own copy.
+
+See what else is bundled:
+
 ```sh
-npx @vegastack/skills list                      # what is bundled, by group
-npx @vegastack/skills add --group dev-skills    # the whole dev workflow, one command
-npx @vegastack/skills add dev-architect         # or a single skill
+npx @vegastack/skills list
 ```
 
 ## Skills in this package
 
 ### `dev-skills` — the issue-driven dev workflow
 
-Install the family with `add --group dev-skills`.
+Install the family with `add --group dev-skills --global`.
 
 | Skill | What it does |
 |---|---|
@@ -58,13 +66,46 @@ These operate on the vegastack-skills repository itself and do nothing useful in
 
 A `--group` or `--all` install is **one transaction**: every skill is checked and staged before any of them is committed, so if one fails, none are installed and the destination is left exactly as it was.
 
+The ten dev-workflow skills:
+
+```sh
+npx @vegastack/skills add --group dev-skills --global
+```
+
+Everything worth installing outside this repo:
+
+```sh
+npx @vegastack/skills add --all --global
+```
+
+Check the family against the manifest:
+
 ```sh
-npx @vegastack/skills add --group dev-skills    # the ten dev-workflow skills
-npx @vegastack/skills add --all                 # everything worth installing in your project
-npx @vegastack/skills verify --group dev-skills # check the family against the manifest
-npx @vegastack/skills remove --group dev-skills # uninstall it again
+npx @vegastack/skills verify --group dev-skills --global
 ```
 
+Uninstall it again:
+
+```sh
+npx @vegastack/skills remove --group dev-skills --global
+```
+
+## Upgrading and health checks
+
+Upgrade to the latest release. `--force` is required because `add` refuses to overwrite an installed copy that differs from the bundle rather than silently discarding local edits:
+
+```sh
+npx @vegastack/skills@latest add --group dev-skills --global --force
+```
+
+Diagnose an install — integrity across all skills, plus installed-vs-latest version:
+
+```sh
+npx @vegastack/skills doctor --global
+```
+
+Run `doctor` without `--global` from inside a project to additionally check that project's `.vegastack/dev.md` profile; the global run skips that check, since the profile is per-project by design.
+
 ## Flags
 
 | Flag | Meaning |
@@ -82,18 +123,22 @@ npx @vegastack/skills remove --group dev-skills # uninstall it again
 
 `--all` and `--agent all` are different axes and are easy to confuse: `--all` chooses **which skills**, `--agent all` chooses **which agent runtimes**. `add --all --agent all --global` is valid and means every installable skill, on every runtime, in your home directory.
 
-Agent targeting is automatic: the CLI detects which agents you have (`~/.claude`, `~/.codex`/`~/.agents`, `~/.hermes`) and targets them without asking — `--agent` overrides. A numbered picker appears only when nothing is detected. Installs are project-local by default; pass `--global` for the home directory (required for Hermes).
+Agent targeting is automatic: the CLI detects which agents you have (`~/.claude`, `~/.codex`/`~/.agents`, `~/.hermes`) and targets them without asking — `--agent` overrides. A numbered picker appears only when nothing is detected.
 
 ## Agent surfaces
 
-| Agent | Project install | Global install |
+`--global` is the recommended install and the only one that can cover all three runtimes at once. `--project` is the flag default, so pass `--global` explicitly.
+
+| Agent | Global install (recommended) | Project install |
 |---|---|---|
-| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
-| Codex | `.agents/skills/` | `~/.agents/skills/` |
-| Hermes | — (Hermes discovers skills globally only) | `~/.hermes/skills/` |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex | `~/.agents/skills/` | `.agents/skills/` |
+| Hermes | `~/.hermes/skills/` | — (Hermes discovers skills globally only) |
 
 `--agent hermes` therefore requires `--global`; `--agent all` on a project install covers codex+claude and prints a notice about hermes.
 
+Prefer a project install when a repository should carry its own copy — so collaborators get the same skills from a checkout, or so one project can pin a version while the rest of the machine moves on. Pick one or the other per skill rather than both: in Claude Code a personal (global) skill takes precedence over a project one, so a project-local copy would not override a global install of the same skill.
+
 ## Integrity model
 
 The package ships a checksum manifest that is verified at install and by `verify` — it proves the installed bytes match what was packed, not who published it. Publisher identity is attested separately by npm provenance, generated by the trusted-publishing release pipeline. Verify it with `npm audit signatures` or on the package's npm page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/skills",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Installer and verifier for VegaStack Agent Skills (Claude Code, Codex, and Hermes)",
   "license": "MIT",
   "type": "module",

package/skill/dev-review/SKILL.md

@@ -13,6 +13,8 @@ Nearest neighbors: `dev-implement` invokes this per dev.md's `review:` knob and
 
 Build the review package first: `git log --oneline <base>..<head>` + `git diff --stat` + `git diff -U10`, written to `.vegastack/.tmp/<issue>-<slug>/review-<base7>..<head7>.diff`. Reviewers get paths — the brief (issue body), the plan comment, the package file, the project's `.vegastack/review-known-patterns.md` — plus the binding constraints copied verbatim. Reviewers write their full reports to `.tmp` files and return short status; a dead reviewer's findings survive on disk.
 
+The guard provisions its own scanner: it locates the SkillSpector CLI through whatever channel installed it (uv, brew, pipx) and runs it by absolute path, so a working install is never reported as missing because `PATH` differs between the operator's shell and the agent's. dev.md's `skillspector-update:` knob decides the rest — `auto` (the default) installs it when absent and upgrades it before each scan, falling back to the installed copy on any failure; `notify` only reports what upstream published; `off` never touches the network. `--no-provision` forces one run to leave the machine alone. An upgrade that changes anything is reported before the findings, because after an upgrade a new finding is the tool having learned something, not the diff having broken something.
+
 When dev.md names a `skill-scan:` root, the security dispatch also gets the scan report: `node <path-to-this-skill>/scripts/skill-scan.mjs --json > .vegastack/.tmp/<issue>-<slug>/skill-scan.json` (add `--llm` for the semantic pass — advisory only, never a gate; it is non-deterministic and a degraded run inflates scores). The same guard runs at `dev-implement`'s Verify gate, so by review time it has already passed; the axis is here to triage what sits below the blocking bar and to judge whether anything above it was suppressed rather than fixed.
 
 ## The axes — parallel, fresh, never merged

package/skill/dev-review/refresh/REFRESH.md

@@ -1,3 +1,18 @@
 # Refresh contract — dev-review
 
-Evergreen: this skill asserts no version pins, numeric vendor limits, or dated claims — its content is review discipline (axes, severities, the bounded loop, dispatch briefs, the smell baseline, cross-agent handoff shape), all versionless. The `codex exec` / `claude -p` invocation forms are deliberately treated as durable CLI surfaces; dev-setup's detection covers their presence per machine. Revisit if a future edit introduces a volatile fact.
+Most of this skill is versionless review discipline (axes, severities, the bounded loop, dispatch briefs, the smell baseline, cross-agent handoff) and asserts nothing that can go stale. The `codex exec` / `claude -p` invocation forms stay deliberately untracked as durable CLI surfaces; dev-setup's detection covers their presence per machine.
+
+**The evergreen waiver was retired on 01-09-2026** (issue #83). `scripts/lib/skillspector.mjs` now parses the output of third-party commands and calls a third-party API, so the skill carries volatile facts for the first time — and the waiver's own escape clause said to revisit exactly then.
+
+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 |
+
+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/dev-review/refresh/sources.json

@@ -1,6 +1,133 @@
 {
   "schemaVersion": 1,
-  "retrievalBaseline": "2026-08-28",
-  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
-  "sources": []
+  "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/dev-review/scripts/lib/skillspector.mjs

@@ -0,0 +1,221 @@
+#!/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 dev-review; 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.
+export function defaultRun(cmd, args, { timeoutMs = 300_000 } = {}) {
+  try {
+    const stdout = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', '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;

package/skill/dev-review/scripts/skill-scan.mjs

@@ -15,6 +15,13 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  defaultRun,
+  latestRelease,
+  locateSkillspector,
+  provisionSkillspector,
+  readVersion,
+} from './lib/skillspector.mjs';
 
 // The clause every suppression must carry, mirroring the "Still flag if:"
 // requirement on .vegastack/review-known-patterns.md entries: a suppression
@@ -173,7 +180,7 @@ export function parseBaseline(text) {
     coverage.push({ skill: raw.skill, file: raw.file, sha256: raw.sha256, reason: raw.reason });
   });
 
-  return { rules, fingerprints: rawFingerprints, coverage, errors, warns };
+  return { rules, fingerprints: rawFingerprints, coverage, errors, warns, scannerVersion: data.scanner_version ?? null };
 }
 
 // Absolute paths, sorted, of the skill directories under `root`. A directory is
@@ -318,13 +325,34 @@ export function evaluateScan(facts) {
     baselineErrors = [],
     skills = [],
     scanErrors = [],
+    skillspector = {},
+    baselinePin = {},
   } = facts;
 
   // Environment failures first: when the scanner never ran, a finding list is
   // not evidence of anything, and the real cause must read before the noise.
   if (binaryMissing) {
-    blocks.push(`the \`skillspector\` binary is not on PATH — ${INSTALL_HINT}, or set skill-scan: none if this project has no skills`);
+    blocks.push(
+      `the \`skillspector\` binary could not be found — no install channel (uv, brew, pipx) reports it and it is not on PATH — ${INSTALL_HINT}; or, if it runs through a wrapper or container, point VSK_SKILLSPECTOR at that executable; or set skill-scan: none if this project has no skills`,
+    );
+  }
+  // An update that could not happen is a note, never a block: the scan ran on
+  // the copy that was already installed, which is exactly the documented
+  // fallback. Sanitized — this text comes from a package manager.
+  if (skillspector.action === 'failed' && skillspector.message) {
+    warns.push(`skillspector update failed, scanned with the installed copy instead — ${safe(skillspector.message)}`);
+  }
+  // A fingerprint is a content hash tied to the scanner that produced it, so a
+  // version change can stop it matching and quietly un-suppress its finding.
+  // Warn, never block: the finding coming back IS the loud outcome, and the pin
+  // is never moved automatically — that would assert a suppression still holds
+  // for a scanner nobody has run.
+  if (baselinePin.fingerprints > 0 && baselinePin.scannerVersion && skillspector.version && baselinePin.scannerVersion !== skillspector.version) {
+    warns.push(
+      `baseline pins scanner_version ${safe(baselinePin.scannerVersion)} for ${baselinePin.fingerprints} fingerprint(s) but skillspector ${safe(skillspector.version)} ran — re-verify those suppressions and move the pin deliberately, never automatically`,
+    );
   }
+
   if (rootMissing) {
     blocks.push(`scan root "${rootMissing}" does not exist — build it first if it is a build output, or correct dev.md's skill-scan: knob`);
   }
@@ -502,6 +530,29 @@ export function scanRootDeclarations(devMdText) {
   return [...String(devMdText ?? '').matchAll(KNOB_LINE)].map((match) => match[1]);
 }
 
+// The sibling knob governing SkillSpector itself: off | notify | auto, absent
+// reading as `auto` so an existing profile inherits the default without an
+// edit. Same tolerant layout matching and same conflict discipline as
+// `skill-scan:` — a knob the guard cannot see reads as absent, and absent must
+// not silently mean something different from what the author wrote.
+//
+// Named for the tool, not for our guard: `skill-scan:` is our machinery,
+// `skillspector-update:` is the third-party binary (operator's rule, 01-09-2026).
+const UPDATE_KNOB_LINE = /^[ \t]*(?:[-*+][ \t]+)?skillspector-update:[ \t]*(\S+)/gm;
+
+export const UPDATE_MODES = new Set(['off', 'notify', 'auto']);
+
+// Every declared value, unvalidated. The caller refuses a conflict or an
+// unrecognised value rather than picking one: guessing which mode the author
+// meant is exactly the judgement a guard must not make.
+export function updateModeDeclarations(devMdText) {
+  return [...String(devMdText ?? '').matchAll(UPDATE_KNOB_LINE)].map((match) => match[1]);
+}
+
+export function resolveUpdateMode(devMdText) {
+  return updateModeDeclarations(devMdText)[0] ?? 'auto';
+}
+
 export function resolveScanRoot(devMdText) {
   const value = scanRootDeclarations(devMdText)[0];
   if (!value || value === 'none') return null;
@@ -529,10 +580,16 @@ function normalizeIssue(raw) {
 // Impure: shells out to the scanner, once per skill. `--baseline` is rejected
 // together with `--recursive` ("scan each sub-skill with its own baseline"), so
 // the loop is the supported path, not an optimization we passed up.
-export function gatherFacts({ root, baselinePath, llm }) {
+export function gatherFacts({ root, baselinePath, llm, binary: binaryOverride }) {
   // VSK_SKILLSPECTOR is a TEST SEAM (stubs the scanner in unit tests), mirroring
-  // ship-gate.mjs's VSK_GH. Normal runs resolve `skillspector` from PATH.
-  const binary = process.env.VSK_SKILLSPECTOR || 'skillspector';
+  // ship-gate.mjs's VSK_GH. `binaryOverride` is the absolute path the CLI
+  // resolved through the tool's own install channel; a bare PATH lookup is the
+  // last resort, not the first.
+  //
+  // Locating deliberately happens in the CLI and NOT here: gatherFacts is
+  // driven directly by unit tests, and probing uv/brew/pipx from inside it
+  // would make the suite shell out to whatever is installed on the machine.
+  const binary = process.env.VSK_SKILLSPECTOR || binaryOverride || 'skillspector';
   const base = {
     binaryMissing: false,
     rootMissing: null,
@@ -551,6 +608,10 @@ export function gatherFacts({ root, baselinePath, llm }) {
     base.baselineErrors = parsed.errors;
     base.baselineWarns = parsed.warns;
     base.coverageAccepted = parsed.coverage;
+    // Only fingerprints are version-coupled: they are content hashes the
+    // scanner computed, so a different scanner may stop matching them. Rules
+    // bind to id+path and survive an upgrade untouched.
+    base.baselinePin = { scannerVersion: parsed.scannerVersion, fingerprints: parsed.fingerprints.length };
   }
   // Short-circuit: with a bad baseline nothing the scan reports is trustworthy —
   // suppressions may not apply — and the scanner would reject the file once per
@@ -685,6 +746,62 @@ export function gatherFacts({ root, baselinePath, llm }) {
   return base;
 }
 
+// The provisioning sequence, extracted so it is testable: the CLI passes the
+// real commands, unit tests pass fakes. Returns the `skillspector` report block.
+//
+// `mode` is a MACHINE policy, never a per-scan-root one — see the CLI, which
+// reads it from the profile even when --root chose what to scan.
+export async function provisionForRun({
+  mode,
+  locate,
+  provision,
+  versionOf,
+  pathVisible,
+  fetchLatest,
+}) {
+  const state = {
+    mode,
+    channel: null,
+    path: null,
+    version: null,
+    action: 'none',
+    before: null,
+    after: null,
+    changed: [],
+    message: '',
+    available: null,
+    resolvedOutsidePath: false,
+  };
+
+  let located = locate();
+  const result = provision({ mode, located });
+  state.action = result.action;
+  state.changed = result.changed;
+  state.message = result.message;
+  state.before = result.before;
+  state.after = result.after;
+  // An install lands somewhere only a fresh probe knows about.
+  if (result.action === 'installed') located = locate();
+
+  if (located) {
+    state.channel = located.channel;
+    state.path = located.path;
+    state.version = versionOf(located.path);
+    // A fresh install has no "before", so its "after" is simply the version now
+    // installed — otherwise the report says "(unchanged)" about a tool that was
+    // not there a moment ago.
+    if (state.action === 'installed') state.after = state.version;
+    // Located through its channel while a bare PATH lookup cannot see it. This
+    // is reported, never warned about: it is the ordinary case this feature
+    // exists to serve, and making it a warn would pin the exit code at 1
+    // forever for exactly the setup that motivated the work.
+    state.resolvedOutsidePath = !pathVisible();
+  }
+
+  if (mode === 'notify') state.available = await fetchLatest();
+  return state;
+}
+
 const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (invokedDirectly) {
   const argv = process.argv.slice(2);
@@ -693,6 +810,8 @@ if (invokedDirectly) {
     return index === -1 ? undefined : argv[index + 1];
   };
   const json = argv.includes('--json');
+  // Forces this one run to leave the machine untouched, whatever the knob says.
+  const noProvision = argv.includes('--no-provision');
   const devMdPath = get('--dev-md') || '.vegastack/dev.md';
 
   let root = get('--root');
@@ -701,6 +820,50 @@ if (invokedDirectly) {
   let outcome = { blocks: [], warns: [] };
   let facts = { skills: [] };
   let baselinePath = get('--baseline') ?? null;
+  let updateMode = 'auto';
+  let binary;
+  // Warns raised before the scan runs. `outcome` is REASSIGNED by evaluateScan,
+  // so anything pushed onto it beforehand would be silently discarded.
+  const preWarns = [];
+  const skillspector = {
+    mode: 'auto',
+    channel: null,
+    path: null,
+    version: null,
+    action: 'none',
+    before: null,
+    after: null,
+    changed: [],
+    message: '',
+    available: null,
+    resolvedOutsidePath: false,
+  };
+
+  // The update mode is read from the profile ALWAYS, including for --root runs.
+  // --root chooses what to scan; it never decides whether this machine may be
+  // written to. Skipping this is how `skillspector-update: off` got ignored on
+  // exactly the invocation dev-review documents for vetting a stranger's skill.
+  {
+    let profileForMode = null;
+    try {
+      profileForMode = readFileSync(devMdPath, 'utf8');
+    } catch {
+      // An explicit --root may legitimately run outside any project.
+    }
+    if (profileForMode !== null) {
+      const declared = [...new Set(updateModeDeclarations(profileForMode))];
+      const unusable = declared.length > 1 || declared.some((value) => !UPDATE_MODES.has(value));
+      // A profile we cannot read unambiguously must not authorise writing to
+      // the machine. The non---root path below turns the same conditions into
+      // blocks; here the run continues, but touching nothing.
+      updateMode = unusable ? 'off' : resolveUpdateMode(profileForMode);
+      if (unusable && explicitRoot) {
+        preWarns.push(
+          `${devMdPath} does not give skillspector-update a single recognised value — this run left the machine untouched`,
+        );
+      }
+    }
+  }
 
   if (!explicitRoot) {
     // "Could not read the profile" and "the profile says none" are different
@@ -720,6 +883,22 @@ if (invokedDirectly) {
           `${devMdPath} gives skill-scan conflicting values (${declared.join(', ')}) — an example line above the real knob would otherwise silently decide the gate; leave exactly one`,
         );
       }
+      const updateDeclared = [...new Set(updateModeDeclarations(devMd))];
+      if (updateDeclared.length > 1) {
+        outcome.blocks.push(
+          `${devMdPath} gives skillspector-update conflicting values (${updateDeclared.join(', ')}) — leave exactly one`,
+        );
+      }
+      const unknown = updateDeclared.filter((value) => !UPDATE_MODES.has(value));
+      if (unknown.length > 0) {
+        // Defaulting an unrecognised value to `auto` would silently install
+        // software because of a typo. The guard refuses instead.
+        outcome.blocks.push(
+          `${devMdPath} sets skillspector-update to ${unknown.join(', ')} — expected one of off, notify, auto`,
+        );
+      }
+      updateMode = resolveUpdateMode(devMd);
+
       root = resolveScanRoot(devMd);
       skipped = root === null && declared.length <= 1;
       // The project's own suppressions apply to the project's own skills. They
@@ -731,23 +910,47 @@ if (invokedDirectly) {
   }
 
   if (!skipped && outcome.blocks.length === 0) {
+    skillspector.mode = noProvision ? 'off' : updateMode;
+
+    // VSK_SKILLSPECTOR is the test seam, and it means "this exact binary" — so
+    // it suppresses locating AND provisioning. Without that, every CLI test
+    // would shell out to whatever uv/brew happen to hold on the machine running
+    // the suite, and a unit suite that installs software is not a unit suite.
+    if (!process.env.VSK_SKILLSPECTOR) {
+      Object.assign(
+        skillspector,
+        await provisionForRun({
+          mode: skillspector.mode,
+          locate: () => locateSkillspector(),
+          provision: ({ mode, located }) => provisionSkillspector({ mode, located }),
+          versionOf: (path) => readVersion({ path }),
+          pathVisible: () => defaultRun('skillspector', ['--version']).ok,
+          fetchLatest: () => latestRelease(),
+        }),
+      );
+      binary = skillspector.path ?? undefined;
+    }
+
     // An uncaught throw would leave node exiting 1 — which in this guard's own
     // scheme reads as "pass with warnings". A crash is not a pass.
     try {
-      facts = gatherFacts({ root, baselinePath, llm: argv.includes('--llm') });
+      facts = gatherFacts({ root, baselinePath, llm: argv.includes('--llm'), binary });
+      facts.skillspector = skillspector;
       outcome = evaluateScan(facts);
     } catch (error) {
-      facts = { skills: [] };
+      facts = { skills: [], skillspector };
       outcome = { blocks: [`the scan failed unexpectedly: ${error.message}`], warns: [] };
     }
   }
 
+  outcome = { ...outcome, warns: [...preWarns, ...outcome.warns] };
   const ok = outcome.blocks.length === 0;
   if (json) {
     console.log(JSON.stringify({
       guard: 'skill-scan',
       ok,
       skipped,
+      skillspector,
       ...outcome,
       // The full normalized issue list, not a count: dev-review's Security axis
       // is told to read the source at each finding's file:line and to judge
@@ -763,6 +966,23 @@ if (invokedDirectly) {
     console.log('skill-scan: BLOCKED');
     for (const b of outcome.blocks) console.log(`  block: ${b}`);
   } else {
+    // The version/dependency change reads BEFORE the findings: after an
+    // upgrade, new findings are the tool having learned something, not the diff
+    // having broken something, and an operator who cannot see that debugs the
+    // wrong thing.
+    if (skillspector.action === 'installed' || skillspector.action === 'upgraded') {
+      const span = skillspector.before === skillspector.after
+        ? `version ${skillspector.version ?? 'unknown'} (unchanged)`
+        : `version ${skillspector.before ?? 'none'} → ${skillspector.after ?? skillspector.version ?? 'unknown'}`;
+      console.log(`skill-scan: skillspector ${skillspector.action} via ${skillspector.channel ?? 'uv'} — ${span}`);
+      for (const line of skillspector.changed) console.log(`    ${line}`);
+    }
+    if (skillspector.action === 'failed') {
+      console.log(`skill-scan: skillspector update failed, continuing with the installed copy — ${skillspector.message}`);
+    }
+    if (skillspector.available && skillspector.available !== skillspector.version) {
+      console.log(`skill-scan: skillspector ${skillspector.available} is available (installed: ${skillspector.version ?? 'unknown'})`);
+    }
     console.log(`skill-scan: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
     for (const entry of facts.skills) {
       console.log(`  ${entry.name}: score ${entry.score} ${entry.severity} — ${entry.issues.length} finding(s)`);

package/skill/dev-setup/SKILL.md

@@ -27,7 +27,7 @@ Facts are your job; decisions are the user's. Gather these silently and present
 | native issue types | `gh api orgs/<org>/issue-types` — an `Epic` type routes parents to it; absent endpoint or type → the `epic` label fallback ([conventions](references/conventions.md)) |
 | Codex CLI (cross-agent review) | `command -v codex` — absent → record the gap in dev.md `## Environments` and recommend installing it |
 | agent skills in the repo | a directory holding skill folders, flat or one group deep — each folder carrying its own entry point — drafts the `skill-scan:` knob at that path; none found drafts `none`. Declare it **once**: a second `skill-scan:` line with a different value, even in a prose example, makes the profile ambiguous and the guard refuses. Where the project builds a flattened bundle the knob names the **built** directory, because unpackaged test fixtures are deliberately adversarial and score higher than anything that ships |
-| SkillSpector (skill scanning) | `command -v skillspector` — absent while `skill-scan:` is set → record it in `## Environments` with `uv tool install git+https://github.com/NVIDIA/skillspector.git`; the guard refuses rather than skipping, so this is a real gap |
+| SkillSpector (skill scanning) | nothing to detect — dev-review's guard locates the CLI through whatever channel holds it (uv, brew, pipx) and, under `skillspector-update: auto`, installs it when absent and upgrades it before each scan. Confirm the drafted `skillspector-update:` value with the operator instead: `auto` is the default and provisions silently, `notify` only reports what upstream published, `off` never touches the network |
 
 Not a git repo, or no origin remote → this is a **greenfield run, not an error**: follow the greenfield playbook in [stack-playbooks](references/stack-playbooks.md) — interview for the intended stack, offer `git init` and `gh repo create` each on its own yes, and render dev.md from the chosen playbook's conventions with TODO lines where machinery doesn't exist yet. A declined remote skips labels and records the TODO plainly.
 
@@ -49,7 +49,7 @@ Ask with your harness's question tool — AskUserQuestion in Claude Code, `reque
 - Playbook matched → show the drafted `## Ship` runbook (each step `auto:`, `ask:`, or `guard:` — every `guard:` line carries its runnable command inline), the `changelog:` convention, and the `release:` knob (per-merge or on-request) for confirmation; a keep-a-changelog convention with no CHANGELOG.md yet → offer to seed the skeleton; no machinery → "Ship: merge only" and move on
 - Guards drafted → offer to write their CI backstop steps into the project's workflow files (the local `guard:` lines run without CI); each file on the user's yes — release guards only, never general CI
 - Environments or run commands detected → confirm the drafted `## Environments` and `## Verify` bullets
-- Agent skills detected → confirm the drafted `skill-scan:` root, the `## Verify` bullet running the guard (preceded by the build command when the root is a build output), and a blocking `guard:` line in `## Ship` before the publish step — the published artifact is what the world installs. Skills detected but the operator declines the scan → `skill-scan: none`, said plainly, not silently omitted
+- Agent skills detected → confirm the drafted `skill-scan:` root, the `skillspector-update:` value (`auto` by default — say plainly that it installs and upgrades the SkillSpector CLI on this machine without asking again, and that `notify` or `off` opt out), the `## Verify` bullet running the guard (preceded by the build command when the root is a build output), and a blocking `guard:` line in `## Ship` before the publish step — the published artifact is what the world installs. Skills detected but the operator declines the scan → `skill-scan: none`, said plainly, not silently omitted
 - Evidence repo (`ui-evidence: playwright`) → default is the owner's **shared** `<owner>/dev-review-evidence`; if it doesn't exist, offer `gh repo create <owner>/dev-review-evidence --private --add-readme` + the layout/retention README — created once, every project points at it. An org naming policy that rejects the name → pick the closest compliant name with the user and record it in the knob (the name is a knob value, not a contract)
 - App architecture detected → confirm the drafted `## Architecture` (hosting, stage, and kind are what detection usually can't fill — ask those); nothing detected → delete the section, the `stack:` line is enough
 - A legacy `.vegastack/arch.md` exists → fold its knob lines into `## Architecture`, offer each dated `notes:` line to the decision register on the user's yes, then offer to delete arch.md

package/skill/dev-setup/assets/dev-profile.md.template

@@ -15,6 +15,7 @@ evidence-repo: {{owner}}/dev-review-evidence   # shared across projects; this pr
 gates: 3                    # 3 = approve/PR/merge · 2 = approve + one "ship it" · 1 = direct-to-main, ship word merges locally and pushes, no PR
 tests: required             # required | logic-only
 skill-scan: none            # ONE line only — directory holding the agent skills to scan (the BUILT one where a bundle is generated) | none. dev-review's guard reads this and refuses if a second line gives a different value
+skillspector-update: auto   # off | notify | auto — how the SkillSpector CLI itself is kept current. auto installs it when absent and upgrades it before each scan, falling back to the installed copy on any failure; notify only reports what upstream has published; off never touches the network. ONE line only, same as above
 merge: squash
 branch: <type>/<issue>-<slug>   # type: feat | fix | docs | chore | refactor — the only place this list lives
 labels: needs-operator needs-plan ready working for-operator risky research quick-build full-plan epic   # epic label marks map parents only where the org has no native Epic issue type

package/skill/skillify/assets/templates/README.md.template

@@ -5,8 +5,10 @@ TODO: one-paragraph summary for humans and agents browsing the repo. The agent e
 ## Install
 
 ```sh
-npx @vegastack/skills add {{name}}{{groupInstallLine}}
+npx @vegastack/skills add {{name}} --global
 ```
+{{groupInstallBlock}}
+`--global` installs into your home directory, where the skill is available in every project; drop it for a project-local install.
 
 ## What's in this skill
 

package/skill/skillify/scripts/scaffold-skill.mjs

@@ -247,9 +247,12 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
   // The generated test imports the repo validator by relative path, so its depth follows the
   // skill's: skills/<name>/tests/ is three levels up, skills/<group>/<name>/tests/ is four.
   const validatorPath = `${group ? '../../../..' : '../../..'}/packages/cli/scripts/validate-skill.mjs`
-  // Only a grouped skill gets the family-install line; an ungrouped one would otherwise ship a
-  // command naming a group that does not exist.
-  const groupInstallLine = group ? `\nnpx @vegastack/skills add --group ${group}   # or the whole ${group} family` : ''
+  // Only a grouped skill gets the family-install block; an ungrouped one would otherwise ship a
+  // command naming a group that does not exist. It is its own fence, not a second line in the
+  // first one: pasting a shared fence would run the alternative too.
+  const groupInstallBlock = group
+    ? `\nOr the whole ${group} family at once:\n\n\`\`\`sh\nnpx @vegastack/skills add --group ${group} --global\n\`\`\`\n`
+    : ''
 
   const outputs = templateFiles.map(([source, output]) => [source, output ?? `tests/${name}.test.ts`])
   const plan = { name, group, target, files: outputs.map(([, output]) => output), wrote: false }
@@ -264,7 +267,7 @@ export async function scaffoldSkill({ name, dir, group = null, write = false, no
         .replaceAll('{{name}}', name)
         .replaceAll('{{date}}', date)
         .replaceAll('{{validatorPath}}', validatorPath)
-        .replaceAll('{{groupInstallLine}}', groupInstallLine)
+        .replaceAll('{{groupInstallBlock}}', groupInstallBlock)
       const destination = join(staging, output)
       await mkdir(dirname(destination), { recursive: true })
       await writeFile(destination, rendered)

package/skill-integrity.json

@@ -89,26 +89,27 @@
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "561e0232d20fc7e6893b38a4c3d7deb41862d60d7b545a98d3ce7ba1d3c7ac06",
+        "SKILL.md": "bb5f2f34d7342052c5c97b628d11976fafc61996c320f568f863c466606284bf",
         "agents/openai.yaml": "3f35d3dc60f179d4ac2526997c4d10173ba3018d06f0dbe77e209ce2978fa702",
         "assets/review-known-patterns.md.template": "7747b807ed18c4c8bf8acdc6481b2f7f27914d932d757c7243a32a41a18d32c5",
         "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/cross-agent.md": "3541715d0563703373ea3d93582119b80356d1cbdee19ce17f958c0f7c914884",
         "references/dispatch-prompts.md": "cb8134a7b6ff9e20ec4db02d0af2f8767f71bf13fa9a21b28b7a586c2747ec1d",
         "references/security-axis.md": "e207071fc48f761f2deb24c73ef4f5ebcf28c130264dab7c3061ae6c0eee6543",
-        "refresh/REFRESH.md": "242c1efe630327abe12bf9db4c4085aaf05b262a4dbd885b12b0f29cdd4a285d",
-        "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
-        "scripts/skill-scan.mjs": "2d74ebd63ffd66cca5208b5dab2984ace47ef4e832e188f6811ff7c2e303095d"
+        "refresh/REFRESH.md": "ae22dc0ecf756310f4c3aa7e2b20d13b94fb26595fb3b4432eb26cbc6fd7b27d",
+        "refresh/sources.json": "2bae54e726ecb43b778eabe5b62bde51d5725d2a58e700940727f275cd5afe16",
+        "scripts/lib/skillspector.mjs": "f4311c0ca61d3a54bf3012817b317667ae783c0ccd8ffc22b5fcb8674e9f937e",
+        "scripts/skill-scan.mjs": "6638c4ea9aaa29524c58946ea69a4149a156cd39491f5c30f028e53ac402f31c"
       }
     },
     "dev-setup": {
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "4b29049b8ce165fb03f554c8784e095cbe97cef16752b57b86321352a1017ce7",
+        "SKILL.md": "17140c694fa2c0fe231f94df85863d2ed69876f61a31a719ca1458821367373e",
         "agents/openai.yaml": "be790c04fdf910e71642cfadf1a7c07c217bf7fad18581610feb4c31a79651f2",
         "assets/agents-section.md.template": "6c9591d50f73e1e05e78c8969c7836767432cf32487af7205b2cb9f4a410440e",
-        "assets/dev-profile.md.template": "26e244b488d181e23ff4b49addd9ab519c8f5d43e2d914638033648a7ca5bd3a",
+        "assets/dev-profile.md.template": "b81517d1b982f5d69e4416e939e2935191adbc396dba8c75d18767672fd95e28",
         "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "references/harness-facts.md": "2be1d81f6a616d40dc865aaeefaf53c61bc13ade4ba1de8fb406c520bf15be40",
         "references/stack-playbooks.md": "8f457c3d0f96e3c99d745b04332590fdf8af53a9694541181d9c878ae0718ea2",
@@ -159,7 +160,7 @@
       "files": {
         "SKILL.md": "310ac32ff4d557cc166a470fd1866060dfc5f03898e8ff3da9c406b84580742b",
         "agents/openai.yaml": "df320cf32a8db06c213f7892844dab810b7e96cfbf32502d25185d4a4167ef87",
-        "assets/templates/README.md.template": "49dccb4e9b5bdb07c254f9142502b3fd11fd5b083d8661b0ae6a567dec79de74",
+        "assets/templates/README.md.template": "74750e59514bff2211b043f6584ed75271529ff4b304e82b207c282396d3e2a1",
         "assets/templates/REFRESH.md.template": "ff86afade565d668333e7f6d0432213760fd68a62b8ba22897a8601b74c94ac0",
         "assets/templates/SKILL.md.template": "b038775f97b13b54227fe41a767a48cdaa922a93d1732f22c2d1d79bff52ca00",
         "assets/templates/openai.yaml.template": "2fbf488369825109d6cad4f17e7b729a40d9e3c43c7f01bc5dfa16361d59c086",
@@ -170,7 +171,7 @@
         "references/eval-playbook.md": "1f463dfea8d69b7022712776794369892643aa020186fe3a3707c493a6c2d4e9",
         "refresh/REFRESH.md": "695f3283b27c14accf4095137898ce1f6dc40749483c5a5705e80aa9693f08c2",
         "refresh/sources.json": "e554e80c72c16dc70587361804db9e0cf2716c128820b2612d5983a009b2b242",
-        "scripts/scaffold-skill.mjs": "849370bd152e488c66753882928cdb18db356f21468647c8e0a51ee58a385183"
+        "scripts/scaffold-skill.mjs": "d9edbe912ca20aad29afe1b0b904f85bbc4c9bfefb2c75e2986949ce00cb7fae"
       }
     }
   }