Sync from monorepo (v2026.921.1)

DOCS.md

@@ -464,7 +464,7 @@ vg review --in-place                 # the same, stated explicitly
 vg review --local                    # deterministic scanners; no hosted model
 vg review --loop                     # review → deterministic patch → re-review
 vg review --base origin/main         # merge-base of HEAD and the base branch
-vg review explain arch-01            # the evidence behind one finding
+vg review explain arch:<rule>:<path> # the evidence behind one finding
 vg review findings-from-diff         # deterministic graph/policy findings only
 vg review propose blast:<node_id> --model forge --json
 ```
@@ -570,21 +570,60 @@ the signed receipt ceremony.
 vg review findings-from-diff
 vg review findings-from-diff --base origin/main
 vg review findings-from-diff --diff pr.patch --format json
-vg review propose blast:<node_id> --model forge --json
 ```
 
 `--diff` reads a unified diff (`-` is stdin). The patch names the files and
 hunks; the code map still has to be built (`vg` or `vg build`). `--format json`
-writes the findings document plus a `publishable` array of correctness rows
-(`kind: "correctness"`, stable `id` used as `finding_key`, producer metadata
-`blast_radius` or `architecture`) for App ingest. When capsule verification
-already emitted a fact for a finding's path, that evidence id is cited on the
-finding and on the publishable `receipts` array — no second receipt system.
-Suggested-fix on those rows is an honest skip — there is no computed PatchIR
-for blast-radius or architecture-policy rows. Propose is dry-run unless you pass
-`--apply --yes` on a topic branch — never the default branch. Local Code Mode
-ids are `spark`, `flow`, and `forge`; hosted Review uses `relay:<slug>`. This
-path does not post a comment or a check run.
+writes the findings document plus a `publishable` array of correctness rows.
+
+| Field | Blast-radius | Architecture-policy |
+| --- | --- | --- |
+| `kind` | `correctness` (top-level only) | `correctness` (top-level only) |
+| `id` / `finding_key` | `blast:{node_id}` or `blast:{path}:{name}` | `arch:{rule}:{path}` |
+| `source` | `scanner` | `scanner` |
+| producer / `scanner_kind` | `blast_radius` | `architecture` |
+| severity | `low` or `medium` | `low`, `medium`, or `high` — never `critical` from version lag |
+| `receipts` | existing capsule `verify:` / `scan:` / `attest:` ids when those facts already exist | same |
+
+Ids are stable across head SHAs: same symbol or rule+path keeps the same key.
+No spaces. Suggested-fix on publishable rows is an honest skip (`null` /
+`skipped_no_patch`) — there is no computed PatchIR for blast-radius or
+architecture-policy rows. Each run also writes
+`.vibgrate/review-propose-handoff.json` (`vg.review.propose-handoff.v1`) so
+`vg review propose` can resolve those ids without a second findings loop.
+This path does not post a comment or a check run.
+
+#### Propose a PatchIR dry-run — `vg review propose`
+
+```bash
+vg review propose blast:<node_id> --model forge --json
+vg review propose blast:<node_id> --model forge --json --base origin/main
+vg review propose arch:<rule>:<path> --model forge --json --findings findings.json
+vg review propose arch:<rule>:<path> --model relay:<slug> --json
+```
+
+Attaches a PatchIR dry-run to one finding id via the VG Code agent loop — there
+is no second Review runtime. Lookup is the current change set, then
+`--findings` JSON (a `vg.review.findings.v1` document or a review receipt),
+then the last-run `.vibgrate/review-propose-handoff.json`. Pass the same
+`--base` / `--in-place` / `--diff` as findings-from-diff when you want that
+change set explicitly.
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--model <id>` | required | `relay:<slug>` (hosted Review) or `spark` \| `flow` \| `forge` (local Code Mode). A bare slug is invalid — propose never calls a backend in that case. |
+| `--loop` | on | VG Code agent loop (capped; stops on no progress) |
+| `--single` | off | One-shot residual → patch → verify instead of the loop |
+| `--apply` | off | Write the patch (still requires `--yes`; refused on the default branch) |
+| `--yes` | off | Consent to write when `--apply` is set |
+| `--base <ref>` | — | Same change set as `findings-from-diff --base` |
+| `--in-place` | off | Same as `findings-from-diff --in-place` |
+| `--diff <file>` | — | Same as `findings-from-diff --diff` (`-` is stdin) |
+| `--findings <file>` | — | Findings JSON when the current change set does not list the id |
+
+Dry-run unless you pass `--apply --yes` on a **topic branch**. It never writes
+the default branch. The same Code Mode and Relay ids are used by `vg code`.
+This command does not post a check run or a review comment.
 
 #### Before you write it — `assess_change`
 

README.md

@@ -603,8 +603,21 @@ vg vex                          # generate an OpenVEX document for attestation
 
 ```bash
 vg review
+vg review findings-from-diff --base origin/main --format json
+vg review propose blast:<node_id> --model forge --json
+vg review propose arch:<rule>:<path> --model forge --json --findings findings.json
 ```
 
+`vg review findings-from-diff` prints the deterministic `vg.review.findings.v1`
+document (blast-radius and architecture-policy `correctness` rows plus security
+scanners) and writes `.vibgrate/review-propose-handoff.json`.
+`vg review propose <id>` attaches a PatchIR dry-run — `--model` is
+`relay:<slug>` (hosted Review) or `spark` | `flow` | `forge` (local Code Mode).
+Lookup is the current change set, then `--findings` JSON, then that last-run
+handoff; pass the same `--base` / `--in-place` / `--diff` as findings-from-diff
+when you want that change set explicitly. It writes nothing unless you pass
+`--apply --yes` on a topic branch.
+
 ---
 
 ## Privacy & offline-first
@@ -747,7 +760,7 @@ All HCS computation runs in an optional, separately-licensed engine module that
 | `vg fix` | Ranked, risk-tiered upgrade plans from the hosted planner — then apply the one you choose |
 | `vg init [path]` | Initialise config and `.vibgrate/` |
 | `vg report` | Generate a report from a scan artifact |
-| `vg review` | **Vibgrate Review** — architecture + security-control review of the current change, locally (`--in-place`, `--local`, `--loop`). Deterministic blast-radius findings from the code graph via `vg review findings-from-diff`; `vg review propose <id>` attaches a PatchIR dry-run. One decision (`pass` / `needs_review` / `fail` / `undetermined`) in a signed receipt (Ed25519 over the receipt digest; `vg review verify <receipt.json>` checks it offline); protected findings cannot be blessed into a pass. Reports change integrity, not a proof of security. Builds or refreshes the code map itself when it is missing or stale (`--no-auto-build` opts out) |
+| `vg review` | **Vibgrate Review** — architecture + security-control review of the current change, locally (`--in-place`, `--local`, `--loop`). Deterministic blast-radius findings from the code graph via `vg review findings-from-diff`; `vg review propose <id>` attaches a PatchIR dry-run (same `--base` / `--in-place` / `--diff`, `--findings`, or `.vibgrate/review-propose-handoff.json`). One decision (`pass` / `needs_review` / `fail` / `undetermined`) in a signed receipt (Ed25519 over the receipt digest; `vg review verify <receipt.json>` checks it offline); protected findings cannot be blessed into a pass. Reports change integrity, not a proof of security. Builds or refreshes the code map itself when it is missing or stale (`--no-auto-build` opts out) |
 | `vg sbom export` / `delta` / `vex` | Export CycloneDX/SPDX SBOM, diff two artifacts, or emit an OpenVEX document |
 | `vg scan [path]` | Scan for upgrade drift |
 | `vg scan --full` | Comprehensive scan: drift + vulnerabilities + a banned-dependency report |

action.yml

@@ -46,7 +46,7 @@ inputs:
   image-tag:
     description: 'Scanner image tag to run (defaults to a pinned, tested release).'
     required: false
-    default: '2026.917.1' # vibgrate:cli-version — stamped by scripts/stamp-release-pins.mjs
+    default: '2026.921.1' # vibgrate:cli-version — stamped by scripts/stamp-release-pins.mjs
   verify:
     description: 'Verify the image cosign signature + provenance before running (requires cosign on the runner).'
     required: false

charts/vibgrate/Chart.yaml

@@ -6,8 +6,8 @@ type: application
 # independently of the CLI. appVersion pins the tested scanner image tag and is
 # stamped to the released @vibgrate/cli calendar version by
 # scripts/stamp-release-pins.mjs (via the marker on the appVersion line below).
-version: 0.1.3
-appVersion: "2026.917.1" # vibgrate:cli-version — stamped by scripts/stamp-release-pins.mjs
+version: 0.1.2
+appVersion: "2026.921.1" # vibgrate:cli-version — stamped by scripts/stamp-release-pins.mjs
 home: https://vibgrate.com
 icon: https://vibgrate.com/web-app-manifest-512x512.png
 sources:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibgrate/cli",
-  "version": "2026.917.1",
+  "version": "2026.921.1",
   "description": "vg — local codebase intelligence CLI + MCP server for AI coding agents: deterministic code graph, drift reporting, and version-correct library docs (Apache-2.0)",
   "//mcpName": "Official MCP registry ownership proof: the registry fetches the published npm package and requires this field to match the com.vibgrate/ai-context server entry (see docs/marketing/mcp-registry/README.md). Must ship in the published @vibgrate/cli package.json.",
   "mcpName": "com.vibgrate/ai-context",
@@ -104,15 +104,15 @@
   },
   "devDependencies": {
     "@tree-sitter-grammars/tree-sitter-hcl": "1.2.0",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.1",
     "@types/semver": "^7.8.0",
     "@typescript-eslint/eslint-plugin": "^8.70.0",
     "@typescript-eslint/parser": "^8.70.0",
     "eslint": "^10.10.0",
     "graphology-types": "^0.24.8",
     "tsup": "^8.0.0",
     "tsx": "^4.23.13",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22.0.0"

packaging/homebrew-tap/Formula/vg.rb

@@ -3,8 +3,8 @@
 class Vg < Formula
   desc "Deterministic, no-API-key code graph for AI assistants (vg)"
   homepage "https://vibgrate.com"
-  url "https://registry.npmjs.org/@vibgrate/cli/-/cli-2026.917.1.tgz"
-  sha256 "13b8468bc5226af571b119d101e050399c556d33aa2d4bf22cdf12dcefb102c1"
+  url "https://registry.npmjs.org/@vibgrate/cli/-/cli-2026.914.1.tgz"
+  sha256 "21c164080d1ba33dc53d604a8754ffa0079daa9c8b771a9053c224a2c43877bf"
   license "Apache-2.0"
   depends_on "node"
 

packaging/scoop-bucket/vg.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026.917.1",
+  "version": "2026.914.1",
   "description": "Deterministic, no-API-key code graph for AI assistants (vg)",
   "homepage": "https://vibgrate.com",
   "license": "Apache-2.0",

plugins/claude/vg/skills/vg/SKILL.md

@@ -3,7 +3,7 @@ name: vg
 description: Query the local code graph (vg) for structure, impact, and navigation instead of grepping/reading many files.
 ---
 
-<!-- vg:v2 · managed by `vg install` — auto-refreshed when these instructions evolve; remove this line to opt out -->
+<!-- vg:v3 · managed by `vg install` — auto-refreshed when these instructions evolve; remove this line to opt out -->
 
 # vg — the code map
 
@@ -48,9 +48,12 @@ When a task needs a library's API, use the docs tools before web search or
 training-data recall — they are official content matched to the version **this
 project has installed**, and they win when the two conflict.
 
-- **Workflow:** `resolve_library` once per library, then `library_docs` with the
-  returned `targetId` and a focused query (good: "zod refine custom error
-  message"; bad: "zod"). Never guess a targetId.
+- **Workflow:** `resolve_library` with the **package name only** (good: `"zod"`).
+  Then `library_docs` with the returned `targetId` and a topic (good: `"refine
+  custom error message"`). Do not send the whole phrase as the resolve query —
+  hosted resolve treats an unknown exact name as `not_found`. Never guess a
+  targetId. If docs return `entityCount` 0, the catalog has no snippet for that
+  version; read `node_modules` instead of retrying the same query.
 - **Budget:** at most **3 docs calls per task**. If 2 `library_docs` calls have
   not surfaced the section you need, read the package source under
   `node_modules` instead of searching again.