@vegastack/skills 0.14.0 → 0.16.1

package/package.json

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

package/skill/dev-architect/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-chronicle/SKILL.md

@@ -20,7 +20,7 @@ Nearest neighbors: `dev-implement` writes the entries at hand-back (the write ru
 - **Changed:** <the user-visible changes, simple words — sub-bullets or one ·-separated line>
 - **Decisions:** <register lines it produced, or "none">
 
-— approved by operator (<username>) · built by <agent> · branch <name>
+— approved by (<username>) · built by <agent> · branch <name>
 ```
 
 - Titles name the outcome ("Invoice reminders now chase late payers"), never the mechanism ("add reminderAt column"). The issue reference is a full markdown link to `…/issues/<n>` (correct for PRs too — GitHub redirects); a bare `#N` never appears anywhere in an entry, because file views don't auto-link it.

package/skill/dev-chronicle/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-debug/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

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-implement/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-intake/SKILL.md

@@ -55,7 +55,7 @@ Before posting any brief, run `node <path-to-this-skill>/scripts/brief-lint.mjs
 
 - A new issue starts at `needs-operator`, plus its scope label; add `risky` when it touches security, money, user data, or production. (Names come from dev.md's `labels:` knob.)
 - Approval is only the operator's explicit words, clearly tied to the issue. Labels, silence, or time never create approval.
-- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the operator (username) format. That comment is what preflight verifies.
+- Record it as one approval marker comment per conventions — `scope=brief`, or `scope=brief+plan` when the inline plan was posted with it — quoting the operator's words in the (username) format. That comment is what preflight verifies.
 - Then flip the state: `research` and `quick-build` → `ready`; `full-plan` → `needs-plan` (dev-plan takes it from there).
 - An issue with an unresolved Assumptions entry cannot leave `needs-operator` — resolve every entry (confirmed, corrected, or moved to a spike) first; the section is deleted once resolved.
 - A directional decision this work settles — one passing the Decisions test in dev.md — is proposed as one register line on the operator's yes; `dev-ship` records at merge.

package/skill/dev-intake/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

package/skill/dev-plan/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

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/assets/review-known-patterns.md.template

@@ -10,7 +10,7 @@ Format, one entry per pattern:
 - **Pattern:** <what the reviewer keeps flagging, concretely — code shape, file area>
 - **Why it's safe here:** <the project fact that makes it a false positive>
 - **Still flag if:** <the exception that makes it a real finding after all>
-- **Origin:** <date + issue where the dismissal happened — operator (<username>)>
+- **Origin:** <date + issue where the dismissal happened — (<username>)>
 ```
 
 The four fields are LIST ITEMS — this file is read in a repo's file view, where single newlines soft-wrap into one paragraph; bullets are what guarantee a line per field. Appended entries (dev-implement's corrections loop) keep the same shape.

package/skill/dev-review/references/conventions.md

@@ -25,14 +25,14 @@ Every workflow-generated issue comment opens with an invisible HTML marker follo
 
 ## Operator identity
 
-Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — is written `operator (<github-username>)`:
+Every human reference in every artifact — approvals, revisions, decisions, changelog attributions, review adjudications — names the operator by their GitHub username in parentheses, with no title before it — `(<github-username>)`:
 
-- Approval: `Approved by operator (<username>) on DD-MM-YYYY: "<their words>"`
-- Register line: `- DD-MM-YYYY operator (<username>) — <decision>`
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
 
 ## Revision markers
 
-Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per operator (<username>) correction`. Existing revision lines are never rewritten.
+Any artifact edited after its first approval: the heading gains `(v2)`, the marker gains `rev=2`, and a `Revisions:` line is appended at the bottom — `v2 — DD-MM-YYYY: <what changed>, per (<username>) correction`. Existing revision lines are never rewritten.
 
 ## Scope classes
 

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