@vegastack/skills 0.16.2 → 0.18.0

package/package.json

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

package/skill/dev-implement/SKILL.md

@@ -17,18 +17,18 @@ When the operator directly asks in chat for a change, their words are the approv
 
 - Run the deterministic guard first: `node <path-to-this-skill>/scripts/preflight.mjs --issue <n> --me $(gh api user -q .login) --json` (add `--repo <o/r> --dev-md <path>` when running outside the project root) — exit 2 stops you with its reasons (open + `ready` state, approval marker, scope label, plan approval on full-plan, Assumptions section, blockers, assignee, repo match); exit 1 passes with warnings — read them into the ledger. Resume and corrections runs pass `--expect working` / `--expect for-operator`.
 - Then the judgment checks: read the complete brief plus parent issue and milestone for context; re-verify the brief's touch points against the current code (things drift between approval and execution) — including the version-impact line; volatile dependency claims per `dev-architect`'s verify protocol; a full-plan issue's plan still matches reality. A material decision left open — even outside a formal Assumptions section — or reality contradicting brief or plan is a stop: one `handback` comment with the smallest question, `needs-operator`.
-- Resuming a dead session's issue: the operator's explicit handover is required; then follow the resume protocol in [ledger-and-resume](references/ledger-and-resume.md) — brief → plan → ledger → `git log`, nothing else.
+- Resuming a dead session's issue: the operator's explicit handover is required; then follow the resume protocol in [ledger-and-resume](references/ledger-and-resume.md) — brief → plan → ledger → `git log`, nothing else. When the claim is instead being abandoned (nothing worth resuming), the operator releases it with `node <path-to-this-skill>/scripts/reclaim.mjs --issue <n>` (`working` → `ready`, unassign; refuses a still-fresh ledger unless `--force`) — never an automatic reclaim.
 
 ## Claim
 
-Assign yourself, swap `ready` → `working`, branch from the default branch per dev.md's `branch:` knob, and **create the ledger comment as your first write**. Record each task's base sha before starting it.
+One session owns one issue, end to end — never hold two `working` claims at once. Assign yourself, swap `ready` → `working`, branch from the default branch per dev.md's `branch:` knob, and **create the ledger comment as your first write** — that comment's edit time is this claim's only liveness signal (dev-status reads a long-silent ledger as a possibly-orphaned claim), so a claim whose session dies before writing it is invisible. Record each task's base sha before starting it.
 
 ## Build — dark, test-first, checkpointed
 
 No progress updates, no questions. A `fix:` issue's diagnosis runs under the `dev-debug` skill — its phases govern the investigation inside this dark mode, and its winning suspect feeds the evidence comment. A spike the brief flagged runs first — its result opens the evidence comment and shapes the rest of the build. Then work the plan task by task:
 
 - **Red before green.** Write the failing test first — at the seams the brief names, never elsewhere — watch it fail for the stated reason, implement the minimal code, watch it pass. One slice at a time. The tests-are-real rubric (implementation-coupled, tautological, horizontal-sliced — defined in `dev-review`'s dispatch prompts) applies to your own tests before a reviewer ever sees them.
-- **Checkpoint the ledger** after every task (tick the plan checkbox in the same pass) and at every ruling, per the reference.
+- **Checkpoint the ledger** after every task — and in the same pass tick the matching `[x]` in the *plan* comment (a second write, to a different comment than the ledger, and the one the operator's progress view reads — so the easiest to skip and the one that silently rots). Checkpoint at every ruling too; each checkpoint is also the claim's heartbeat, so never batch them "for later," per the reference.
 - **Transitory artifacts** — subagent reports, scratch diffs, drafts — live in `.vegastack/.tmp/<issue>-<slug>/`; subagents write full output to files there and return short status.
 - Decide routine things yourself and ledger the rulings. A structural choice mid-build — a new dependency, table, or service — checks `dev-architect`'s trigger discipline first; a moving part with no named trigger is a stop condition.
 - **The scope ratchet is a stop condition:** work revealed bigger than the issue's scope class (or plainly exceeding one session) → one `handback` comment proposing the upgrade or split (dev-plan's ratchet rules), `needs-operator`, stop.
@@ -71,7 +71,7 @@ Run the `dev-review` skill per dev.md's `review:` knob — fresh subagent axes b
 Branch: <name> @ <sha7>
 ```
 
-The tail's sha stays bare: GitHub auto-links a 7-character sha mid-comment as soon as the commit is on the remote, so the tail becomes a live commit link the moment the branch is pushed — while an explicit `/commit/<sha>` link written at hand-back points at a commit that has not been pushed yet, and 404s. The `**Review:**` line is the one home of surfaced rulings: every ledger `Ruling:` appears there, in the order made. Run `node <path-to-this-skill>/scripts/evidence-check.mjs --file <draft> --json` before posting — exit 2 means the shape is incomplete; fix, don't post. Post it, swap `working` → `for-operator`, stop, and close with the plain-language summary (which repeats, never replaces, the evidence content): what was built, which paths were taken, the rulings, what's worth the operator double-checking.
+The tail's sha stays bare: GitHub auto-links a 7-character sha mid-comment as soon as the commit is on the remote, so the tail becomes a live commit link the moment the branch is pushed — while an explicit `/commit/<sha>` link written at hand-back points at a commit that has not been pushed yet, and 404s. The `**Review:**` line is the one home of surfaced rulings: every ledger `Ruling:` appears there, in the order made. Run `node <path-to-this-skill>/scripts/evidence-check.mjs --file <draft> --issue <n> --json` before posting — it checks the draft's shape and, with `--issue`, that the plan comment's `[x]` boxes reflect the ledger's completed tasks; exit 2 means the shape is incomplete or the checkboxes lag the ledger — fix, don't post. Post it, swap `working` → `for-operator`, stop, and close with the plain-language summary (which repeats, never replaces, the evidence content): what was built, which paths were taken, the rulings, what's worth the operator double-checking.
 
 ## Corrections loop — code and docs move together
 

package/skill/dev-implement/references/ledger-and-resume.md

@@ -6,16 +6,18 @@ The ledger comment's format, line vocabulary, and the resume read-order (brief
 
 Create the ledger comment as the session's **first write after claiming** — before any code — with just the marker and heading. Then checkpoint, editing in place:
 
-- **After each plan task completes** — and tick the matching checkbox in the plan comment in the same pass. Record the task's base sha *before* starting it, so the `complete` line's commit range is exact.
+- **After each plan task completes** — and tick the matching `[x]` in the plan comment in the same pass. That box is a second write, to a different comment, that your own resume path never reads — so it is the one that silently lags reality, while the operator's progress view depends on it. The hand-back guard (`evidence-check --issue`) blocks when the ledger's completed tasks outnumber the plan's checked boxes. Record the task's base sha *before* starting it, so the `complete` line's commit range is exact.
 - **After each review fix round**, with the addressed/open counts.
 - **At every dark-mode judgment call.** A ruling is any decision the brief/plan didn't make for you that a reviewer or the operator could reasonably question. Rulings are cheap; unrecorded decisions are debt.
 - **On findings deferred or parked at review**, per dev-review's adjudication lines.
 
 Never batch checkpoints "for later" — the ledger's value is exactly that a crash between checkpoints loses one task, not the map. Under concurrent edits, last-writer-wins on one comment is accepted (single-operator workflow); note a clobber if you ever see one.
 
+The ledger's edit time is also this claim's **heartbeat** — the only liveness signal an agent session exposes. dev-status reads a ledger silent past the orphan threshold (6h) as a *possibly-orphaned* claim: the session likely died before hand-back. A session that runs for days but keeps checkpointing never trips it; a dead one's ledger freezes. A single long task can legitimately go quiet — so checkpoint at rulings within it too, keeping the pulse alive — and the flag is always the operator's to act on (check, resume, or reclaim), never an automatic reset.
+
 ## Resuming — dev-implement's additions to the protocol
 
-- The takeover of a `working` issue requires the operator's explicit handover word; the protocol never makes claiming automatic.
+- The takeover of a `working` issue requires the operator's explicit handover word; the protocol never makes claiming automatic. When nothing is worth resuming, the operator releases the claim instead with `scripts/reclaim.mjs --issue <n>` — `working` → `ready`, unassigned — which refuses a ledger still fresh under the orphan threshold unless `--force`.
 - Corroborate, don't re-verify: the commits the ledger names should exist in `git log` — reconcile the ranges; a mismatch is a `handback`, not a guess.
 - A task whose last line is a fix round is mid-loop — resume at the next round with the open findings; a later `complete` line supersedes earlier rounds.
 - Recorded rulings bind the resumed session: build on them, and surface disagreement in the evidence comment instead of re-litigating.

package/skill/dev-implement/scripts/evidence-check.mjs

@@ -7,7 +7,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseFlags, parseMarker, renderResult } from './lib/gh.mjs';
+import { GhUnavailable, findMarkerComment, ghJson, parseFlags, parseMarker, renderResult } from './lib/gh.mjs';
 
 const REQUIRED_SECTIONS = [
   [/\*\*Done:\*\*/, '**Done:** section'],
@@ -38,18 +38,66 @@ export function checkEvidence(text) {
   return { blocks, warns: [] };
 }
 
+// The plan comment's checkboxes and the ledger's completed tasks are two records
+// of the same fact, and the checkbox — a second write, to a different comment
+// than the ledger the session already maintains — is the one that silently rots.
+// At hand-back the ledger's completed tasks must be reflected in the plan's
+// checkboxes, or the operator reads a false x/y. Distinct task numbers with a
+// `complete` line in the ledger, versus `[x]` boxes in the plan.
+export function checkTaskConsistency(comments) {
+  const blocks = [];
+  const warns = [];
+  const plan = findMarkerComment(comments, 'plan')?.comment?.body;
+  const ledger = findMarkerComment(comments, 'ledger')?.comment?.body;
+
+  // No plan comment, or a plan with no checkboxes (e.g. a research issue), is
+  // nothing to reconcile — not a violation. No ledger yet is the same.
+  if (!plan || !ledger) return { blocks, warns };
+  const planDone = (plan.match(/^-\s*\[x\]/gim) ?? []).length;
+  const planTotal = planDone + (plan.match(/^-\s*\[ \]/gm) ?? []).length;
+  if (planTotal === 0) return { blocks, warns };
+
+  const completeTasks = new Set();
+  for (const m of ledger.matchAll(/^-\s*Task\s+(\d+):\s*complete\b/gim)) completeTasks.add(m[1]);
+  const ledgerComplete = completeTasks.size;
+
+  if (ledgerComplete > planDone) {
+    blocks.push(`${ledgerComplete} task(s) are marked complete in the ledger but only ${planDone} of ${planTotal} are checked off in the plan comment — tick the matching [x] boxes before hand-back`);
+  }
+  return { blocks, warns };
+}
+
+// Fetch the issue's comments and reconcile plan checkboxes against the ledger.
+// Fails closed: an unreachable gh blocks rather than passing silently.
+function taskConsistencyFromIssue({ issue, repo: repoFlag }) {
+  const repo = repoFlag || ghJson(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
+  const comments = ghJson(['api', `repos/${repo}/issues/${issue}/comments`, '--paginate']);
+  return checkTaskConsistency(comments);
+}
+
 const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (invokedDirectly) {
   const flags = parseFlags(process.argv.slice(2));
   let outcome;
   if (!flags.file) {
-    outcome = { blocks: ['usage: evidence-check.mjs --file <evidence.md> [--json]'], warns: [] };
+    outcome = { blocks: ['usage: evidence-check.mjs --file <evidence.md> [--issue <n> --repo <o/r>] [--json]'], warns: [] };
   } else {
     try {
       outcome = checkEvidence(readFileSync(flags.file, 'utf8'));
     } catch (error) {
       outcome = { blocks: [`cannot read evidence: ${error.message}`], warns: [] };
     }
+    // Consistency check only when an issue is named — keeps the file-shape check
+    // network-free by default. A gh failure fails closed onto the block list.
+    if (flags.issue) {
+      try {
+        const consistency = taskConsistencyFromIssue(flags);
+        outcome.blocks.push(...consistency.blocks);
+        outcome.warns.push(...consistency.warns);
+      } catch (error) {
+        outcome.blocks.push(error instanceof GhUnavailable ? `cannot verify plan/ledger consistency: ${error.message}` : `consistency check error: ${error.message}`);
+      }
+    }
   }
   const { exitCode, text } = renderResult('evidence-check', outcome, { json: Boolean(flags.json) });
   console.log(text);

package/skill/dev-implement/scripts/reclaim.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// dev-implement reclaim: release an orphaned claim. The operator runs this after
+// dev-status flags a working issue as possibly-orphaned — it resets working →
+// ready and unassigns, so a fresh session can claim it cleanly. It NEVER claims
+// or resumes: a takeover still needs the operator's explicit handover to a new
+// session. It fails closed and refuses to release a claim whose ledger is still
+// fresh (the session may be alive) unless --force is passed.
+//
+// Exit codes: 0 released · 2 refused/blocked (reasons printed). Read-verify runs
+// before any mutation, so a block never leaves a half-released issue.
+// Usage: node reclaim.mjs --issue <n> [--repo o/r] [--orphan-hours 6] [--force] [--json]
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GhUnavailable, findMarkerComment, ghJson, parseFlags, renderResult } from './lib/gh.mjs';
+
+const WORKING = 'working';
+const READY = 'ready';
+
+const ageHours = (iso, now) => Math.floor((now - Date.parse(iso)) / 3_600_000);
+
+// Read-verify: the deterministic facts that must hold before a release. Returns
+// { blocks, plan } — plan is the mutation to run when blocks is empty.
+export function evaluateReclaim({ issue, comments, orphanHours = 6, force = false, now = Date.now() }) {
+  const blocks = [];
+  const labels = (issue.labels ?? []).map((l) => l.name);
+
+  if (issue.state && issue.state !== 'open') blocks.push(`issue is ${issue.state} — only an open working issue can be reclaimed`);
+  if (!labels.includes(WORKING)) blocks.push(`issue is not '${WORKING}' (labels: [${labels.join(', ') || 'none'}]) — nothing to reclaim`);
+
+  const moved = findMarkerComment(comments, 'ledger')?.comment?.updated_at ?? null;
+  const ageH = moved ? ageHours(moved, now) : null;
+  if (!force && ageH !== null && ageH < orphanHours) {
+    blocks.push(`ledger moved ${ageH}h ago (< orphan threshold ${orphanHours}h) — this claim may be live; pass --force to release anyway`);
+  }
+
+  const assignees = (issue.assignees ?? []).map((a) => a.login);
+  return {
+    blocks,
+    plan: { removeAssignees: assignees, ledgerAgeHours: ageH },
+  };
+}
+
+function ghRun(args) {
+  try {
+    return execFileSync(process.env.VSK_GH || 'gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error) {
+    const stderr = error.stderr?.toString().trim() || error.message;
+    throw new GhUnavailable(`gh ${args.join(' ')} failed: ${stderr}`);
+  }
+}
+
+export function gatherAndReclaim(flags) {
+  const repo = flags.repo || ghJson(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
+  const issueNumber = flags.issue;
+  const raw = ghJson(['api', `repos/${repo}/issues/${issueNumber}`]);
+  const comments = ghJson(['api', `repos/${repo}/issues/${issueNumber}/comments`, '--paginate']);
+  const orphanRaw = Number(flags['orphan-hours']);
+  const { blocks, plan } = evaluateReclaim({
+    issue: { state: raw.state, labels: raw.labels, assignees: raw.assignees },
+    comments,
+    orphanHours: Number.isFinite(orphanRaw) && orphanRaw >= 1 ? orphanRaw : 6,
+    force: Boolean(flags.force),
+  });
+  if (blocks.length > 0) return { blocks, warns: [] };
+
+  // Mutations, only past a clean read-verify. Label swap first (frees the
+  // claim), then unassign, then the operator-visible note.
+  ghRun(['issue', 'edit', String(issueNumber), '-R', repo, '--remove-label', WORKING, '--add-label', READY]);
+  for (const login of plan.removeAssignees) {
+    ghRun(['issue', 'edit', String(issueNumber), '-R', repo, '--remove-assignee', login]);
+  }
+  const age = plan.ledgerAgeHours === null ? 'no ledger comment was ever written' : `ledger silent ${plan.ledgerAgeHours}h`;
+  const note = `**Claim released.** \`${WORKING}\` → \`${READY}\`, unassigned — ${age}. The prior session did not hand back; its branch and ledger stand. Resume it (dev-implement, the operator's handover) or let a fresh session claim it.`;
+  ghRun(['issue', 'comment', String(issueNumber), '-R', repo, '--body', note]);
+  return { blocks: [], warns: [`released #${issueNumber}: ${WORKING} → ${READY}, unassigned (${age})`] };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const flags = parseFlags(process.argv.slice(2), ['json', 'force']);
+  let outcome;
+  if (!flags.issue) {
+    outcome = { blocks: ['usage: reclaim.mjs --issue <n> [--repo o/r] [--orphan-hours 6] [--force] [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = gatherAndReclaim(flags);
+    } catch (error) {
+      outcome = { blocks: [error instanceof GhUnavailable ? `cannot verify: ${error.message}` : `reclaim error: ${error.message}`], warns: [] };
+    }
+  }
+  const { exitCode, text } = renderResult('reclaim', outcome, { json: Boolean(flags.json) });
+  console.log(text);
+  process.exit(exitCode);
+}

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/dev-status/SKILL.md

@@ -12,10 +12,10 @@ Nearest neighbors: `dev-chronicle` answers "how did we get here"; this skill ans
 ## Gather
 
 ```
-node <path-to-this-skill>/scripts/status.mjs --stale-days 3 --json
+node <path-to-this-skill>/scripts/status.mjs --orphan-hours 6 --json
 ```
 
-Read-only; it returns the board (open issues per state label with age, scope, risky), task progress `x/y` from plan-comment checkboxes, ledger movement for `working` issues (stale = no ledger edit within `--stale-days`, default 3), open PRs with check state, pending unrecorded `Decision:` proposals, and the last chronicle entry. Exit 2 = cannot verify (offline, unauthenticated) — report the gap plainly and stop; never render a guessed board.
+Read-only; it returns the board (open issues per state label with age, scope, risky), task progress `x/y` from plan-comment checkboxes, ledger movement for `working` issues in hours (`possiblyOrphaned` = the ledger has been silent past `--orphan-hours`, default 6, or was never written — the claim's heartbeat has stopped), open PRs with check state, pending unrecorded `Decision:` proposals, and the last chronicle entry. Exit 2 = cannot verify (offline, unauthenticated) — report the gap plainly and stop; never render a guessed board.
 
 ## Render — names, never bare numbers
 
@@ -26,8 +26,8 @@ Needs you (N):
 - <linked title> — <state> <age>d: <one line: what it waits for and the word needed>
 Waiting on plan (N): - <linked title> — needs-plan <age>d
 Ready to build (N): - <linked title> — <scope>
-In flight (N): - <linked title> — working, task <x>/<y>, ledger moved <n>d ago
-Stale (N): - <linked title> — working <age>d, ledger silent <n>d → check or reclaim
+In flight (N): - <linked title> — working, task <x>/<y>, ledger moved <n>h ago
+Possibly orphaned (N): - <linked title> — working <age>d, ledger silent <n>h → heartbeat stopped; check, resume, or reclaim (`reclaim.mjs --issue <n>`)
 Open PRs (N): - <linked title> — checks <green|pending-or-red|no-checks>
 Pending decisions (N): "<gist-plain>" (<linked issue>) — records at that issue's merge
 Last chronicle chapter: <date> — <title-plain>
@@ -38,9 +38,10 @@ Next: <the single most valuable operator action, and why>
 - Sections with zero entries are omitted, not rendered empty. A completely quiet board is one line: "Nothing needs you — <n> issues ready for agents, nothing in flight."
 - `risky` issues get their flag shown inline wherever they appear.
 - **Next** is one line, chosen not computed-looking: the action that unblocks the most (a plan approval blocking several ready issues beats a lone review).
+- **Possibly orphaned** is the ledger heartbeat gone silent past the orphan window (or never started) — likely a dead session, not certainly one. Surface it with the `reclaim.mjs` command inline; the operator decides (check the session, hand it to a resume, or release the claim). A long-running task that keeps checkpointing never lands here.
 - <linked title> means a markdown link this report builds around the issue/PR title and its URL; numbers ride inside the link, never stand alone. That governs the references the board itself makes.
 - `<title-plain>` / `<gist-plain>` are the script's `titlePlain` / `gistPlain` fields — text quoted from elsewhere (a chronicle title, a decision gist) may arrive carrying markdown links, and raw bracket-and-parenthesis markup means nothing in a terminal, so it is quoted with the markup removed rather than relinked.
 
 ## Honesty rules
 
-Data comes only from the script; ordering, the wait-reason one-liners, and Next are the skill's judgment — clearly judgment, never dressed as data. A stale `working` issue is a fact to surface, not an accusation: "check or reclaim" is the operator's call (a takeover still needs their explicit handover, per dev-implement). Close with the plain-language summary only when invoked as part of a larger run; standalone, the report IS the summary.
+Data comes only from the script; ordering, the wait-reason one-liners, and Next are the skill's judgment — clearly judgment, never dressed as data. A possibly-orphaned `working` issue is a fact to surface, not an accusation — the ledger heartbeat went silent, which is likely but not certainly a dead session: "check, resume, or reclaim" is the operator's call (a takeover still needs their explicit handover, and `reclaim.mjs` is theirs to run, per dev-implement). Close with the plain-language summary only when invoked as part of a larger run; standalone, the report IS the summary.

package/skill/dev-status/scripts/status.mjs

@@ -2,7 +2,7 @@
 // dev-status data gatherer: everything the board report needs, deterministically,
 // read-only, markers-only. The skill renders; this script never invents state.
 //
-// Usage: node status.mjs [--repo o/r] [--stale-days 3] [--dev-md <path>] --json
+// Usage: node status.mjs [--repo o/r] [--orphan-hours 6] [--dev-md <path>] --json
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -46,6 +46,15 @@ export function ageDays(iso, now = Date.now()) {
   return Math.floor((now - Date.parse(iso)) / 86_400_000);
 }
 
+// Ledger liveness is measured in hours, not days: a session that hands back in
+// hours can go dark for a fraction of a day, which whole-day granularity cannot
+// even represent. The ledger's updated_at is the only liveness proxy an agent
+// session exposes — a live session (even a multi-day one) checkpoints and keeps
+// this small; a dead one freezes it.
+export function ageHours(iso, now = Date.now()) {
+  return Math.floor((now - Date.parse(iso)) / 3_600_000);
+}
+
 export function parseMarker(body) {
   const match = /<!--\s*vsk:v1\s+([^>]*?)\s*-->/.exec(body ?? '');
   if (!match) return null;
@@ -110,7 +119,7 @@ export function checksState(rollup) {
   return rollup.every(ok) ? 'green' : 'pending-or-red';
 }
 
-export function gatherStatus({ repo, staleDays = 3, devMdPath = '.vegastack/dev.md', chroniclePath = '.vegastack/chronicle.md', now = Date.now() } = {}) {
+export function gatherStatus({ repo, orphanHours = 6, devMdPath = '.vegastack/dev.md', chroniclePath = '.vegastack/chronicle.md', now = Date.now() } = {}) {
   const resolvedRepo = repo || gh(['repo', 'view', '--json', 'nameWithOwner']).nameWithOwner;
   const devMdText = existsSync(devMdPath) ? readFileSync(devMdPath, 'utf8') : '';
   const knobs = readKnobs(devMdText);
@@ -133,8 +142,12 @@ export function gatherStatus({ repo, staleDays = 3, devMdPath = '.vegastack/dev.
       const comments = gh(['api', `repos/${resolvedRepo}/issues/${issue.number}/comments`, '--paginate']);
       issue.tasks = taskProgress(comments);
       const moved = ledgerMovedAt(comments);
-      issue.ledgerAgeDays = moved ? ageDays(moved, now) : null;
-      issue.stale = bucket === knobs.states[3] && (issue.ledgerAgeDays === null || issue.ledgerAgeDays >= staleDays);
+      issue.ledgerAgeHours = moved ? ageHours(moved, now) : null;
+      // possiblyOrphaned: a working issue whose ledger has been silent past the
+      // orphan threshold — or which never got a ledger comment at all (claimed,
+      // then died before its first write). A fact for the operator to act on,
+      // never an automatic reclaim: the reset is theirs to run.
+      issue.possiblyOrphaned = bucket === knobs.states[3] && (issue.ledgerAgeHours === null || issue.ledgerAgeHours >= orphanHours);
       decisions.push(...pendingDecisions(comments, registerText).map((d) => ({ issue: issue.number, gist: d, gistPlain: stripLinks(d) })));
     }
   }
@@ -151,7 +164,7 @@ export function gatherStatus({ repo, staleDays = 3, devMdPath = '.vegastack/dev.
     if (m) lastChronicle = { date: m[1], title: m[2], titlePlain: stripLinks(m[2]) };
   }
 
-  return { repo: resolvedRepo, staleDays, board, prs, pendingDecisions: decisions, lastChronicle };
+  return { repo: resolvedRepo, orphanHours, board, prs, pendingDecisions: decisions, lastChronicle };
 }
 
 const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
@@ -159,8 +172,8 @@ if (invokedDirectly) {
   const argv = process.argv.slice(2);
   const get = (f) => { const i = argv.indexOf(f); return i === -1 ? undefined : argv[i + 1]; };
   try {
-    const staleDaysRaw = Number(get('--stale-days'));
-    const data = gatherStatus({ repo: get('--repo'), staleDays: Number.isFinite(staleDaysRaw) && staleDaysRaw >= 1 ? staleDaysRaw : 3, devMdPath: get('--dev-md') });
+    const orphanRaw = Number(get('--orphan-hours'));
+    const data = gatherStatus({ repo: get('--repo'), orphanHours: Number.isFinite(orphanRaw) && orphanRaw >= 1 ? orphanRaw : 6, devMdPath: get('--dev-md') });
     console.log(JSON.stringify(data, null, argv.includes('--json') ? 2 : 0));
   } catch (error) {
     console.error(`status: cannot verify — ${error.message}`);

package/skill-integrity.json

@@ -48,15 +48,16 @@
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "f79f4d312f6c03ffdcf2e2fd44169e48520445900389e2d469c0946811be3801",
+        "SKILL.md": "1b38469b3fc0feedf8650ad1f9bfda35485406dc81de89a66e5ab57c670bc798",
         "agents/openai.yaml": "1abab383deca54d32749fd9156f9a6211fe96e02e0166dc8a16ff8459ac31b74",
         "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
-        "references/ledger-and-resume.md": "5e3deae2af67735940564e04adcbc23c0c0dc86da2f6c80d68b8c1207c8f5900",
+        "references/ledger-and-resume.md": "974fe4895973aca4ce05ad3eca05c71f1bbb518a59027732c459cc3331fb2f98",
         "refresh/REFRESH.md": "7b854109d897b78b3055bf1ab89517afdca65c12eb65a4d009141e3ee11cf58f",
         "refresh/sources.json": "7bd883e5b3512e236a909ad6ff20c97f3555785867c31fd728256c7c2c514c74",
-        "scripts/evidence-check.mjs": "9a360e6c5460d46b271b28457ee6be92f165c54c771c2dc6860c4a52e6890a9a",
+        "scripts/evidence-check.mjs": "974e343ae5372e8b3c930d4ba05e48b29ea5204048f9d2c3cdc8b89237933d8c",
         "scripts/lib/gh.mjs": "d2261e4b3e2d7b3cdc58123b1503c0264664d7e5a258e90d0caa79333466975a",
-        "scripts/preflight.mjs": "1bf47b6d147c8603e28d96f7c81f2b4db61b60a3811190ca96b36d83129820d5"
+        "scripts/preflight.mjs": "1bf47b6d147c8603e28d96f7c81f2b4db61b60a3811190ca96b36d83129820d5",
+        "scripts/reclaim.mjs": "fea8299765ded7052a724e55399f40a1769d91f218df7c38922859800065fa73"
       }
     },
     "dev-intake": {
@@ -89,26 +90,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",
@@ -133,12 +135,12 @@
       "group": "dev-skills",
       "repoOnly": false,
       "files": {
-        "SKILL.md": "56415c2f69bb1a2fcb488b9846a20e632eb902b05c5b2b58ae9206d3eaffd77b",
+        "SKILL.md": "1e4742805f8f6c99f36e3eea4171b39e336d14aad001d5309b507bf6efa40ae7",
         "agents/openai.yaml": "72435947f5afef0c8a2c170e987b14fe6057b174318c16b6b538ae8d129791fb",
         "references/conventions.md": "95bf916cc11f95f3d5eefcb34db4fbc05d88ae1c8f08869800dfa417f8da17ed",
         "refresh/REFRESH.md": "52aee9bae64d8342e127704d1db282e43ed57c101148727bf10172d6cb975bfa",
         "refresh/sources.json": "a7ba2340964dc70410626087686145b5790a0e763a18ef2c4d9aa37e950f2e04",
-        "scripts/status.mjs": "bc56d0b5d996676cfccb752d9d77d0e9e7d64932741cd39d6a503e9761fbe34d"
+        "scripts/status.mjs": "f6672ef38cbe31a2335633a96567977d9b885390f1f766bf63f6dd7d172c987b"
       }
     },
     "skill-maintainer": {