@vegastack/skills 0.13.0 → 0.16.0

package/README.md

@@ -3,16 +3,19 @@
 Installer for VegaStack Agent Skills — a family of self-contained skills for Claude Code, Codex, and Hermes, shipped in one integrity-checked package.
 
 ```sh
-npx @vegastack/skills list
-npx @vegastack/skills add dev-architect
+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
 ```
 
 ## Skills in this package
 
+### `dev-skills` — the issue-driven dev workflow
+
+Install the family with `add --group dev-skills`.
+
 | Skill | What it does |
 |---|---|
-| `skill-maintainer` | Encodes the Agent Skills standards (Claude Code, Codex, Hermes, agentskills.io) for creating, updating, and releasing skills in a skills repo |
-| `skillify` | Turns a feature or workflow into a complete skill conforming to the VegaStack skills contract, or audits an existing one |
 | `dev-setup` | Bootstraps any project, greenfield included, for the issue-driven dev workflow: stack-playbook-drafted profile, AGENTS.md section, labels, guards, decision register |
 | `dev-intake` | Turns ideas, brainstorms, and SOWs into agent-ready GitHub issues with recorded user approval |
 | `dev-plan` | Plans an approved issue before any code exists: fresh-grounded questionnaire, strict plan format with Interfaces blocks, the scope ratchet, quick-build inline mode |
@@ -24,26 +27,60 @@ npx @vegastack/skills add dev-architect
 | `dev-status` | The operator's board: whose move is it, from deterministic gh data |
 | `dev-chronicle` | The project's narrative record: story entries per branch and the "catch me up" digest |
 
+### `repo-tooling` — repo-only
+
+These operate on the vegastack-skills repository itself and do nothing useful in another project, so **`--all` skips them**. Install one by name if you are contributing to that repo.
+
+| Skill | What it does |
+|---|---|
+| `skill-maintainer` | Encodes the Agent Skills standards (Claude Code, Codex, Hermes, agentskills.io) for creating, updating, and releasing skills in a skills repo |
+| `skillify` | Turns a feature or workflow into a complete skill conforming to the VegaStack skills contract, or audits an existing one |
+
 ## Commands
 
 | Command | What it does |
 |---|---|
 | `list` | Show the bundled skills |
-| `add <skill>` | Install (or upgrade) a skill into the selected agent directories |
-| `verify [skill]` | Check installed copies against the bundled checksum manifest (all bundled skills when no name given) |
+| `add <selection>` | Install (or upgrade) skills into the selected agent directories |
+| `verify [selection]` | Check installed copies against the bundled checksum manifest (all bundled skills when nothing is selected) |
 | `doctor` | Diagnose an install: integrity across all skills, dev profile (`.vegastack/dev.md`) presence, installed-vs-latest version |
-| `remove <skill>` | Uninstall a skill from the selected agent directories |
+| `remove <selection>` | Uninstall skills from the selected agent directories |
+
+### Selecting what to act on
+
+`add`, `verify`, and `remove` each take **exactly one** selector. Combining two is an error, not a merge.
+
+| Selector | Means |
+|---|---|
+| `<skill>` | That one skill. Works for every bundled skill, repo-only ones included |
+| `--group <group>` | Every skill in that group |
+| `--all` | Every bundled skill **except** the repo-only ones |
+
+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.
+
+```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
+```
 
 ## Flags
 
 | Flag | Meaning |
 |---|---|
 | `--project` / `--global` | Install into the current project (default) or the user's home directory |
+| `--group NAME` | Select every skill in a group (see `list` for the groups) |
+| `--all` | Select every bundled skill except the repo-only ones |
 | `--agent codex\|claude\|hermes\|both\|all` | Target agent runtime(s); `both` = codex+claude |
-| `--dir PATH` | Operate on a different project directory |
+| `--dir PATH` | Operate on a different project directory; not valid with `--global` |
 | `--dry-run` | Show what would change without writing |
 | `--force` | Overwrite a modified installed copy |
 | `--non-interactive` | Skip prompts and use defaults: `--agent both`, project-local (for automation) |
+| `--version` / `-v` | Print the installer version |
+| `--help` / `-h` | Print usage |
+
+`--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).
 

package/dist/index.js

@@ -3,20 +3,69 @@
 // src/index.ts
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, cp, lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
+
+// src/selection.ts
+var sorted = (names) => [...new Set(names)].sort();
+function groupsIn(catalog) {
+  return sorted(catalog.map((entry) => entry.group).filter((group) => group !== null));
+}
+function selectSkills(selector, catalog, verb = "install") {
+  const chosen = [
+    selector.skill ? "a skill name" : null,
+    selector.group ? "--group" : null,
+    selector.all ? "--all" : null
+  ].filter(Boolean);
+  if (chosen.length > 1) {
+    throw new Error(`Use only one of ${chosen.join(", ")} — they select different things and are not combined`);
+  }
+  if (selector.all) {
+    const installable = sorted(catalog.filter((entry) => !entry.repoOnly).map((entry) => entry.name));
+    if (!installable.length) {
+      throw new Error("Nothing to install: every bundled skill is repo-only. Name one explicitly, or use --group, to install it anyway.");
+    }
+    return installable;
+  }
+  if (selector.group) {
+    const members = sorted(catalog.filter((entry) => entry.group === selector.group).map((entry) => entry.name));
+    if (!members.length) {
+      const groups2 = groupsIn(catalog);
+      throw new Error(`Unknown group: ${selector.group}. Available groups: ${groups2.length ? groups2.join(", ") : "(none)"}`);
+    }
+    return members;
+  }
+  if (selector.skill) {
+    if (!catalog.some((entry) => entry.name === selector.skill)) {
+      throw new Error(`Unknown skill: ${selector.skill}. Bundled skills: ${sorted(catalog.map((entry) => entry.name)).join(", ")}`);
+    }
+    return [selector.skill];
+  }
+  const groups = groupsIn(catalog);
+  throw new Error(`Specify what to ${verb}: a skill name (${sorted(catalog.map((entry) => entry.name)).join(", ")})` + `${groups.length ? `, --group (${groups.join(", ")})` : ""}, or --all`);
+}
+
+// src/index.ts
 var packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 var bundleRoot = join(packageRoot, "skill");
 var surfaces = { codex: ".agents/skills", claude: ".claude/skills", hermes: ".hermes/skills" };
 var packageVersion = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")).version;
 function usage() {
   return `Usage: vegastack-skills <add|verify|remove> <skill> [options]
+       vegastack-skills <add|verify|remove> --group <group> [options]
+       vegastack-skills <add|verify|remove> --all [options]
        vegastack-skills <list|doctor> [options]
 
+Select exactly one of: a skill name, --group <group>, or --all.
+--all installs every skill except the repo-only ones; name those explicitly.
+A --group or --all install is one transaction: if any skill fails, none are installed.
+
 Options:
+  --group NAME                           install every skill in that group
+  --all                                  every bundled skill except the repo-only ones
   --agent codex|claude|hermes|both|all   (both = codex+claude; hermes is global-only)
   --project | --global
   --dir PATH
@@ -34,12 +83,21 @@ async function bundledSkills() {
 }
 function parse(argv) {
   const command = argv[0] && !argv[0].startsWith("-") ? argv.shift() : "help";
-  const options = { command, dryRun: false, force: false, nonInteractive: false };
+  const options = { command, all: false, dryRun: false, force: false, nonInteractive: false };
   if (argv[0] && !argv[0].startsWith("-"))
     options.skill = argv.shift();
   while (argv.length) {
     const flag = argv.shift();
-    if (flag === "--agent")
+    if (flag === "--group") {
+      const value = argv.shift();
+      if (value === undefined || value === "" || value.startsWith("-"))
+        throw new Error("--group requires a value");
+      if (options.group !== undefined)
+        throw new Error("--group may be given only once; select one group per run");
+      options.group = value;
+    } else if (flag === "--all")
+      options.all = true;
+    else if (flag === "--agent")
       options.agent = argv.shift();
     else if (flag === "--project")
       options.mode = "project";
@@ -68,13 +126,19 @@ function parse(argv) {
     throw new Error("--dir cannot be combined with --global");
   return options;
 }
-async function requireSkill(options) {
-  const skills = await bundledSkills();
-  if (!options.skill)
-    throw new Error(`Specify a skill: ${skills.join(", ")}`);
-  if (!skills.includes(options.skill))
-    throw new Error(`Unknown skill: ${options.skill}. Bundled skills: ${skills.join(", ")}`);
-  return options.skill;
+async function skillCatalog() {
+  const manifest = await loadManifest();
+  return Object.entries(manifest.skills).map(([name, entry]) => ({
+    name,
+    group: entry.group ?? null,
+    repoOnly: Boolean(entry.repoOnly)
+  }));
+}
+function hasSelector(options) {
+  return Boolean(options.skill || options.group || options.all);
+}
+async function requireSelection(options, verb = "install") {
+  return selectSkills({ skill: options.skill, group: options.group, all: options.all }, await skillCatalog(), verb);
 }
 var agentLabels = { claude: "Claude Code", codex: "Codex", hermes: "Hermes" };
 async function detectAgents() {
@@ -330,51 +394,69 @@ async function compare(destination, files) {
   return { status: issues.length ? "drifted" : "verified", issues };
 }
 async function install(options) {
-  const skillName = await requireSkill(options);
+  const skillNames = await requireSelection(options);
   const choice = await prompt(options);
   const base = baseFor(choice.mode, options.dir);
   const agents = resolveAgents(choice.agent, choice.mode);
   if (!agents.length)
     return;
   if (!options.dryRun)
-    return withInstallLock(base, () => installLocked(options, skillName, agents, base));
-  return installLocked(options, skillName, agents, base, false);
+    return withInstallLock(base, () => installLocked(options, skillNames, agents, base));
+  return installLocked(options, skillNames, agents, base, false);
 }
-async function installLocked(options, skillName, agents, base, recover = true) {
+async function installLocked(options, skillNames, agents, base, recover = true) {
   if (recover)
     await recoverInstall(base);
-  const { source, files } = await loadSource(skillName);
+  const sources = new Map;
+  for (const skillName of skillNames)
+    sources.set(skillName, await loadSource(skillName));
   const operations = [];
-  for (const agent of agents) {
-    const destination = join(base, surfaces[agent], skillName);
-    await assertNoSymlink(destination);
-    const parent = dirname(destination);
-    await assertNoSymlink(parent);
-    const existed = await exists(destination);
-    if (existed) {
-      const comparison = await compare(destination, files);
-      if (comparison.status === "verified" && !options.force) {
-        console.log(`unchanged ${agent}: ${destination}`);
-        continue;
+  const refusals = [];
+  for (const skillName of skillNames) {
+    const { files } = sources.get(skillName);
+    for (const agent of agents) {
+      const destination = join(base, surfaces[agent], skillName);
+      await assertNoSymlink(destination);
+      const parent = dirname(destination);
+      await assertNoSymlink(parent);
+      const existed = await exists(destination);
+      if (existed && !(await stat(destination)).isDirectory()) {
+        throw new Error(`Refusing to install over a non-directory: ${destination} — remove it and retry`);
       }
-      if (!options.force) {
-        if (options.dryRun) {
-          console.log(`would replace ${agent} (requires --force; installed copy differs): ${destination}`);
+      if (existed) {
+        const comparison = await compare(destination, files);
+        if (comparison.status === "verified" && !options.force) {
+          console.log(`unchanged ${agent}: ${destination}`);
           continue;
         }
-        throw new Error(`Refusing differing installation without --force: ${destination}`);
+        if (!options.force) {
+          if (options.dryRun) {
+            refusals.push({ agent, path: destination });
+            continue;
+          }
+          throw new Error(`Refusing differing installation without --force: ${destination}`);
+        }
       }
+      const suffix = randomUUID();
+      operations.push({ skill: skillName, agent, destination, existed, stage: join(parent, `.${skillName}.stage-${suffix}`), backup: existed ? join(parent, `.${skillName}.backup-${suffix}`) : undefined });
     }
-    const suffix = randomUUID();
-    operations.push({ skill: skillName, agent, destination, existed, stage: join(parent, `.${skillName}.stage-${suffix}`), backup: existed ? join(parent, `.${skillName}.backup-${suffix}`) : undefined });
   }
   if (options.dryRun) {
     for (const operation of operations)
       console.log(`would install ${operation.agent}: ${operation.destination}`);
+    for (const destination of refusals)
+      console.log(`would replace ${destination.agent} (requires --force; installed copy differs): ${destination.path}`);
+    if (refusals.length && skillNames.length > 1) {
+      console.log(`this run would install nothing: ${refusals.length} destination(s) differ and --force was not given`);
+      process.exitCode = 1;
+    }
     return;
   }
-  if (!operations.length)
+  if (!operations.length) {
+    if (skillNames.length > 1)
+      console.log(`${skillNames.length} skills already installed and unchanged${options.group ? ` (${options.group})` : ""}`);
     return;
+  }
   const journalPath = join(base, ".vegastack", ".skills-install-transaction.json");
   const staged = [];
   const applied = [];
@@ -382,8 +464,9 @@ async function installLocked(options, skillName, agents, base, recover = true) {
     for (const operation of operations) {
       await mkdir(dirname(operation.destination), { recursive: true });
       await assertNoSymlink(dirname(operation.destination), false);
+      const { source, files } = sources.get(operation.skill);
       await cp(source, operation.stage, { recursive: true, dereference: false, errorOnExist: true });
-      await writeFile(join(operation.stage, ".vegastack-install.json"), `${JSON.stringify({ installer: "@vegastack/skills", version: packageVersion, skill: skillName, files }, null, 2)}
+      await writeFile(join(operation.stage, ".vegastack-install.json"), `${JSON.stringify({ installer: "@vegastack/skills", version: packageVersion, skill: operation.skill, files }, null, 2)}
 `, { flag: "wx" });
       const stagedCheck = await compare(operation.stage, files);
       if (stagedCheck.status !== "verified")
@@ -432,13 +515,21 @@ async function installLocked(options, skillName, agents, base, recover = true) {
   await syncDirectory(dirname(journalPath));
   for (const operation of applied)
     console.log(`installed ${operation.agent}: ${operation.destination}`);
+  if (skillNames.length > 1) {
+    const skipped = options.all ? (await skillCatalog()).filter((entry) => entry.repoOnly).map((entry) => entry.name) : [];
+    const note = skipped.length ? ` (skipped ${skipped.length} repo-only: ${skipped.join(", ")} — name one explicitly to install it)` : "";
+    const installedCount = new Set(applied.map((operation) => operation.skill)).size;
+    const unchanged = skillNames.length - installedCount;
+    const unchangedNote = unchanged > 0 ? `, ${unchanged} already up to date` : "";
+    console.log(`installed ${installedCount} skills${options.group ? ` from ${options.group}` : ""}${unchangedNote}${note}`);
+  }
 }
 async function verify(options) {
   const choice = await prompt(options);
   const base = baseFor(choice.mode, options.dir);
   const agents = resolveAgents(choice.agent, choice.mode);
-  const explicit = Boolean(options.skill);
-  const skills = explicit ? [await requireSkill(options)] : await bundledSkills();
+  const explicit = hasSelector(options);
+  const skills = explicit ? await requireSelection(options, "verify") : await bundledSkills();
   let failed = false;
   let found = 0;
   for (const skillName of skills) {
@@ -485,48 +576,74 @@ async function latestPublishedVersion() {
   }
 }
 async function removeSkill(options) {
-  const skillName = await requireSkill(options);
+  const skillNames = await requireSelection(options, "remove");
   const choice = await prompt(options);
   const base = baseFor(choice.mode, options.dir);
   const agents = resolveAgents(choice.agent, choice.mode);
   if (!options.dryRun)
-    return withInstallLock(base, () => removeLocked(options, skillName, agents, base));
-  return removeLocked(options, skillName, agents, base);
-}
-async function removeLocked(options, skillName, agents, base) {
-  let removed = 0;
-  for (const agent of agents) {
-    const destination = join(base, surfaces[agent], skillName);
-    if (!await exists(destination)) {
-      console.log(`not installed ${agent}: ${destination}`);
-      continue;
-    }
-    await assertNoSymlink(destination, false);
-    if (!options.force) {
-      const { files } = await loadSource(skillName);
-      const comparison = await compare(destination, files);
-      if (comparison.status === "drifted")
-        throw new Error(`Installation differs from the bundled skill (possibly locally modified); re-run with --force to remove anyway: ${destination}`);
-    }
-    if (options.dryRun) {
-      console.log(`would remove ${agent}: ${destination}`);
-      continue;
+    return withInstallLock(base, () => removeLocked(options, skillNames, agents, base));
+  return removeLocked(options, skillNames, agents, base, false);
+}
+async function removeLocked(options, skillNames, agents, base, recover = true) {
+  if (recover)
+    await recoverInstall(base);
+  const targets = [];
+  for (const skill of skillNames) {
+    for (const agent of agents) {
+      const destination = join(base, surfaces[agent], skill);
+      if (!await exists(destination)) {
+        console.log(`not installed ${agent}: ${destination}`);
+        continue;
+      }
+      await assertNoSymlink(destination, false);
+      if (!options.force) {
+        const { files } = await loadSource(skill);
+        const comparison = await compare(destination, files);
+        if (comparison.status === "drifted")
+          throw new Error(`Installation differs from the bundled skill (possibly locally modified); re-run with --force to remove anyway: ${destination}`);
+      }
+      targets.push({ skill, agent, destination });
     }
-    await rm(destination, { recursive: true, force: true });
-    removed += 1;
-    console.log(`removed ${agent}: ${destination}`);
   }
-  if (!removed && !options.dryRun)
+  if (options.dryRun) {
+    for (const target of targets)
+      console.log(`would remove ${target.agent}: ${target.destination}`);
+    return;
+  }
+  for (const target of targets) {
+    await rm(target.destination, { recursive: true, force: true });
+    console.log(`removed ${target.agent}: ${target.destination}`);
+  }
+  if (options.all) {
+    const skipped = (await skillCatalog()).filter((entry) => entry.repoOnly).map((entry) => entry.name);
+    if (skipped.length)
+      console.log(`left ${skipped.length} repo-only skills in place: ${skipped.join(", ")} — name one explicitly to remove it`);
+  }
+  if (!targets.length)
     process.exitCode = 1;
 }
 async function list() {
   const manifest = await loadManifest();
-  for (const skillName of await bundledSkills()) {
-    const skill = await readFile(join(bundleRoot, skillName, "SKILL.md"), "utf8");
+  const entries = await skillCatalog();
+  const groups = [...new Set(entries.map((entry) => entry.group).filter((group) => group !== null))].sort();
+  const show = async (entry) => {
+    const skill = await readFile(join(bundleRoot, entry.name, "SKILL.md"), "utf8");
     const description = skill.match(/^description: (.+)$/m)?.[1] ?? "";
-    const fileCount = Object.keys(manifest.skills[skillName]?.files ?? {}).length;
-    console.log(`${skillName} (${fileCount} files)`);
-    console.log(`  ${description.length > 160 ? `${description.slice(0, 157)}...` : description}`);
+    const fileCount = Object.keys(manifest.skills[entry.name]?.files ?? {}).length;
+    console.log(`  ${entry.name} (${fileCount} files)${entry.repoOnly ? "  [repo-only: not installed by --all]" : ""}`);
+    console.log(`    ${description.length > 160 ? `${description.slice(0, 157)}...` : description}`);
+  };
+  for (const group of groups) {
+    console.log(`${group}  —  vegastack-skills add --group ${group}`);
+    for (const entry of entries.filter((item) => item.group === group).sort((a, b) => a.name.localeCompare(b.name)))
+      await show(entry);
+    console.log("");
+  }
+  const ungrouped = entries.filter((entry) => entry.group === null).sort((a, b) => a.name.localeCompare(b.name));
+  if (ungrouped.length) {
+    console.log("ungrouped");
+    for (const entry of ungrouped)
+      await show(entry);
   }
 }
 async function doctor(options) {

package/package.json

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

package/skill/dev-implement/SKILL.md

@@ -47,6 +47,7 @@ A changeset entry's first line is **one plain sentence** naming the change in be
 Before claiming ANY status: **identify** the command that proves it → **run** it fresh and complete → **read** the full output and exit code → only then claim, with the evidence. Tests pass ⇒ a fresh run with 0 failures — never "should pass", never a previous run. Build succeeds ⇒ exit 0. Bug fixed ⇒ the original symptom re-tested. A subagent finished ⇒ you inspected its diff or report file — never its say-so.
 
 - Run what dev.md's `tests:` knob requires; a `risky` issue gets focused security, failure, and recovery checks on top. When dev.md has a `## Verify` runbook, run the app and smoke-check the flows it names. Verify is pre-merge only; post-release checks live in `## Ship` and belong to dev-ship.
+- Run the skill-scan guard here, unconditionally: `node <path-to-dev-review>/scripts/skill-scan.mjs --json` — it reads dev.md's `skill-scan:` knob itself and exits 0 saying it skipped when the project authors no skills, so there is no condition to remember. Exit 2 blocks the hand-back: fix the finding, or take it to the operator for a justified baseline rule — never widen a suppression to get past it. Its findings below the blocking bar are the security axis's to triage at review.
 - UI changed and `ui-evidence: playwright` → capture screenshots of the key states and upload to the shared evidence repo (dev.md `evidence-repo`) under `<this-repo-name>/<issue-number>/<timestamp>-<name>.png` via the contents API, never a clone: `base64 < <file> | tr -d '\n' | gh api -X PUT repos/<evidence-repo>/contents/<path> -f message="evidence #<issue>" -F content=@-` (piped stdin so large screenshots never hit argv limits; timestamped names avoid collisions; a 409 from a concurrent upload just means retry). Link them in the evidence comment — links, never embeds (private-repo images don't render inline). Evidence repo unreachable → name local paths and say so; the hand-back never blocks on it.
 - dev.md's Ship or Verify section is an empty TODO next to visible machinery → finish normally, then suggest re-running dev-setup.
 

package/skill/dev-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-review
-description: Independent review of finished implementation work — a diff against its brief and plan. Use when dev-implement's review step runs, when asked to "review this branch/diff/issue", "give this a second pair of eyes", "check the finished work on issue N", when a cross-agent session (Claude or Codex) is handed a REVIEW REQUEST, or when review findings need a fix loop, re-review, or adjudication. Not for reviewing an unbuilt plan (dev-plan's approval gate), architecture review (dev-architect), shipping gates (dev-ship), or generic PR review in repos outside this workflow.
+description: Independent review of finished implementation work — a diff against its brief and plan — and the skill-scan vulnerability guard. Use when dev-implement's review step runs, when asked to "review this branch/diff/issue", "give this a second pair of eyes", "check the finished work on issue N", when a cross-agent session (Claude or Codex) is handed a REVIEW REQUEST, when review findings need a fix loop, re-review, or adjudication, or when asked to scan skills for vulnerabilities, triage scanner findings, or judge whether a third-party skill is safe to install. Not for reviewing an unbuilt plan (dev-plan's approval gate), architecture review (dev-architect), shipping gates (dev-ship), or generic PR review in repos outside this workflow.
 ---
 
 # dev-review
@@ -13,13 +13,15 @@ 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.
 
+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
 
 | Axis | Runs | Judges |
 |---|---|---|
 | **Spec** | always | the diff vs the CURRENT brief + plan: missing, scope creep, implemented-but-wrong — quoting the brief line per finding; includes the tests-are-real rubric |
 | **Standards** | always | project rules (known-patterns file + repo docs, which override) + the fixed smell baseline pasted in full into its prompt |
-| **Security** | on `risky`, or when touch points hit auth, money, user data, or external input | data-flow traces, exploitability before severity — method in [security-axis](references/security-axis.md) |
+| **Security** | on `risky`, when touch points hit auth, money, user data, or external input, **or when the diff touches a skill under dev.md's `skill-scan:` root** | data-flow traces, exploitability before severity, and triage of the skill scan's findings — method in [security-axis](references/security-axis.md) |
 
 Each axis is a fresh subagent with no memory of writing the code (its prompt: [dispatch-prompts](references/dispatch-prompts.md)). Axes report separately and are never re-ranked into one list — a change can pass one axis and fail another, and merging lets one mask the other.
 
@@ -59,6 +61,11 @@ Severities: `[CRITICAL]` (security axis: exploitable now — blocks) > `[MUST-FI
 
 - Default quiet profile: spec, bugs, and security always; style only where a documented rule exists. The comment count is the noise metric.
 - `.vegastack/review-known-patterns.md` (seed: [template](assets/review-known-patterns.md.template)) holds the project's never-flag patterns — each entry REQUIRES a **"Still flag if:"** exception clause; a suppression without one is a blind spot. Operator dismissals of findings get appended there by dev-implement's corrections loop, so a dismissed pattern stays dismissed.
+- The skill scan's suppressions follow the same discipline in its own baseline file, and the guard enforces the clause rather than trusting it — a rule scoped `id:` with no `path:` is a repo-wide blind spot. A finding suppressed rather than fixed is a review finding, not a settled matter.
+
+## A scan with no issue attached
+
+A scan run outside an issue — a standalone check, or the pre-publish guard in dev.md's `## Ship` — has no review comment to land in, and never gets attached to an unrelated issue. Findings there route to `dev-intake`: offer the operator one `risky` issue whose **brief body** carries the findings, their locations, and what is already known about each cause. That is intake's job, with its questions, its scope call, and its approval — not a comment posted somewhere convenient.
 
 ## Cross-agent — the independence upgrade
 

package/skill/dev-review/references/dispatch-prompts.md

@@ -88,6 +88,18 @@ violations of documented standards may be [MUST-FIX]; baseline smells are
 
 Compose the security dispatch from [security-axis](security-axis.md): the shared preamble above, then that file's Method steps, finding format (the three extra lines), severity definitions, and standing red lines, quoted into the prompt — the reviewer must receive them in full, not a pointer it cannot follow.
 
+Where a scanner report exists, add its path and that file's "Scanner evidence" rules to the same dispatch:
+
+```
+Scanner report: <path to skill-scan.json or the project's equivalent>.
+Treat every entry as a CANDIDATE finding, never a verdict: read the source at
+its file:line, trace the flow, and assign severity yourself by exploitability.
+The report's aggregate score is context, not a ranking. Entries the baseline
+suppressed are in scope — judge whether each rule is scoped as narrowly as its
+cause and whether its stated re-trigger condition would actually fire. Say so
+in your verdict line if the report says the scan did not complete.
+```
+
 ## Re-review brief (scoped, every fix round)
 
 ```

package/skill/dev-review/references/security-axis.md

@@ -1,6 +1,18 @@
 # The security axis
 
-Runs on `risky` issues, and whenever the diff's touch points hit an auth surface, money, user data, or externally-controlled input — the trigger is the surface, not the label alone.
+Runs on `risky` issues, whenever the diff's touch points hit an auth surface, money, user data, or externally-controlled input, and whenever the diff touches a skill under dev.md's `skill-scan:` root — the trigger is the surface, not the label alone.
+
+## Scanner evidence — a finding's start, never its end
+
+Where the project runs a scanner (this family ships `scripts/skill-scan.mjs` for agent skills; a project may name others), its report is an **input to this axis**, on the same footing as the diff. It is evidence, not a verdict:
+
+- **A scanner hit is a candidate finding.** It arrives with a rule ID and a `file:line` and nothing else — no data flow, no attacker, no exploitability. Promote it to a finding only after the Method below fills those in; a hit you cannot trace goes to the collapsed low-confidence block like any other hunch.
+- **Read the source at the location before judging it.** The scanner matched text; whether that text is a vulnerability is your call, made against the file, not the summary.
+- **Severity is yours, not the scanner's.** Map its finding onto this file's ladder by exploitability. A scanner HIGH that cannot be exploited is not `[CRITICAL]`; a scanner MEDIUM with a traced path to a real sink can be.
+- **Never downgrade an unexplained HIGH or CRITICAL** on reputation, score, or "it's our own code". Either the trace shows why it does not hold, or it stands.
+- **The aggregate risk score is not a finding.** It is distorted upward by documentation of the very mechanics being scanned and downward by unrelated suppressions. Quote it for context; never rank on it.
+- **Suppressions are in scope for this axis.** A finding silenced by a baseline rule rather than fixed is reviewable: check the rule is scoped as narrowly as its cause and that its stated re-trigger condition is one that would actually fire.
+- **A degraded or partial scan is not a clean scan.** If the report says the run did not complete, say so in the verdict line rather than reporting its numbers.
 
 ## Method — evidence before severity