@vyuhlabs/dxkit 2.4.8 → 2.5.1

package/templates/.claude/skills/dxkit-learn/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dxkit-learn
+description: Answer questions about dxkit — what each scanner does, what a baseline is, what the 6 health dimensions score, how guardrails work. Use when the user asks "what does dxkit X do?", "what's a baseline?", "what's the slop score?", "how do hooks fit in?", or anything else about dxkit concepts.
+---
+
+# dxkit-learn
+
+This skill explains how dxkit works. Reach for it when the user asks about dxkit concepts before they take an action.
+
+## Mental model
+
+dxkit measures a codebase along **6 dimensions** (Security, Code Quality, Tests, Documentation, Maintainability, Developer Experience) using deterministic scanners (gitleaks, semgrep, cloc, jscpd, graphify, ruff, eslint, …). Findings are anchored to a **baseline** (`.dxkit/baselines/main.json`) so today's pre-existing issues don't block tomorrow's PR. A **guardrail check** diffs current state against the baseline and blocks net-new regressions. Hooks + CI wire the guardrail into the developer's workflow.
+
+The three contracts to remember:
+
+1. **Baseline = the brownfield anchor**. Pre-existing findings are recorded once; future scans only block on *additions*.
+2. **Hooks fire fast (pre-push); CI fires thorough**. Both use the same guardrail logic.
+3. **Reports are deterministic** — same code + same baseline = same findings. The salt mode (`deterministic` vs `random`) controls per-finding identity stability across runs.
+
+## The 6 dimensions
+
+Each dimension is a 0-100 score with letter grade (A≥80, B≥60, C≥40, D≥20, E<20):
+
+| Dimension | What scores it down |
+|---|---|
+| **Security** | Secret leaks (gitleaks), SAST findings (semgrep), dependency vulns (osv-scanner / npm-audit / pip-audit / etc.), TLS-bypass patterns |
+| **Code Quality** | Lint findings (eslint / ruff / golangci-lint / clippy / detekt / rubocop / dotnet-format), high duplication (jscpd), code-pattern slop |
+| **Tests** | Missing test coverage on primary-architecture files; missing test runner config; below-threshold line coverage |
+| **Documentation** | Missing/empty README; missing doc-comments on public APIs (XML-doc/JSDoc/TSDoc/godoc/etc.); below-threshold comment ratio |
+| **Maintainability** | Function/file size outliers, deep cyclomatic complexity, god-objects, high orphan-module count, dead imports |
+| **Developer Experience** | Missing `.gitignore` / `.editorconfig` / `package.json` engines pin / devcontainer / hooks / CI workflow |
+
+Run `vyuh-dxkit health` to see all six at once. Each dimension report has a "top actions" list — the changes that would lift the score the most.
+
+## The scanner toolchain
+
+dxkit doesn't write parsers — it orchestrates established tools and computes scores. The full list is in `TOOL_DEFS` (or run `vyuh-dxkit tools list`). Key ones:
+
+- **gitleaks** — secret scanning (API keys, AWS credentials, GitHub tokens)
+- **semgrep** — multi-language SAST (auto config picks rulesets per active language pack)
+- **cloc** — language-aware line counting (excludes comments + blanks)
+- **jscpd** — copy-paste detection
+- **graphify** — AST-based metrics (functions, classes, cohesion, god-nodes, dead imports)
+- **osv-scanner** — dependency vulnerabilities (npm/pip/cargo/go/gem/maven via OSV.dev)
+- Per-language linters: eslint (TS), ruff (Python), golangci-lint (Go), clippy (Rust), dotnet-format (C#), detekt (Kotlin), pmd (Java), rubocop (Ruby)
+
+If a tool isn't installed, dxkit degrades gracefully (the affected dimension reports a partial score with a "missing tool" note instead of crashing).
+
+## Baselines explained
+
+A baseline is the per-finding identity snapshot of a scan. Every finding has a **fingerprint** (SHA-1[0:16] of file+rule+line-window+content). The baseline stores those fingerprints. The guardrail diffs today's scan against the baseline:
+
+- Fingerprint in scan + in baseline → **existing** (ignored)
+- Fingerprint in scan + NOT in baseline → **added** (blocks)
+- Fingerprint in baseline + NOT in scan → **removed** (silently good)
+
+That's why "fix a critical, leave the medium" works — the medium's fingerprint stays in the baseline; only net-new findings count.
+
+Commands:
+
+```bash
+vyuh-dxkit baseline create               # Capture current state into .dxkit/baselines/main.json
+vyuh-dxkit baseline show                 # Summarize what's recorded
+vyuh-dxkit baseline show --kind secret   # Drill into a specific finding kind
+vyuh-dxkit guardrail check               # Diff current scan vs baseline; exit 1 on net-new
+```
+
+## Hooks
+
+Two hooks ship under `.githooks/`:
+
+- **pre-push** (always-on under `--full`): runs the guardrail check before code leaves the developer's machine. Fast on warm scanner caches (~10-30s).
+- **pre-commit** (opt-in via `--with-precommit-hook`): same logic, fires on every commit. Slower on large repos until incremental scanning lands.
+
+Activation is wired via `npm postinstall` so `npm install` after `git clone` sets `core.hooksPath = .githooks` automatically.
+
+## How to learn more
+
+- `vyuh-dxkit <subcommand> --help` — flag reference
+- `vyuh-dxkit baseline show` — what your repo already has recorded
+- `.dxkit/reports/` — every analyzer's markdown + JSON output from the last run
+- `vyuh-dxkit dashboard` — single HTML view of every report
+
+When the user asks specifically about a scanner or a finding type, point them at the relevant report or run the relevant analyzer command directly.

package/templates/.claude/skills/dxkit-reports/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: dxkit-reports
+description: Run dxkit reports and explain their output. Use when the user asks "run health", "check security", "show me the dashboard", "what does this score mean", or anything about generating / reading dxkit analyzer output. Hands off to dxkit-action for fixing findings.
+---
+
+# dxkit-reports
+
+This skill runs dxkit analyzers and reads their output back to the user. It's the "tell me how my codebase is doing" surface.
+
+## Command map
+
+| User asks | Command | Output |
+|---|---|---|
+| "Overall health" / "give me the score" | `vyuh-dxkit health` | 6-dimension score table + top actions per dimension |
+| "Check security" / "find vulns" | `vyuh-dxkit vulnerabilities` | Code-level SAST + dep-vuln + secret findings, grouped by severity |
+| "Test coverage gaps" | `vyuh-dxkit test-gaps` | Source files without matching tests, prioritized by architectural role |
+| "Code quality" | `vyuh-dxkit quality` | Lint findings + duplication + slop score |
+| "Who's been working on what" | `vyuh-dxkit dev-report` | Per-author activity, hot files, churn |
+| "License inventory" | `vyuh-dxkit licenses` | Every dependency's declared license |
+| "Bill of materials" | `vyuh-dxkit bom` | Licenses + dep vulnerabilities joined (15-col XLSX-ready output) |
+| "Run everything" | `vyuh-dxkit report` | Every analyzer in one shot, ~3-5 min |
+| "Show me the dashboard" | `vyuh-dxkit dashboard` | Single HTML view of all reports — opens at `.dxkit/reports/dashboard.html` |
+
+## Where output lands
+
+Every analyzer writes to `.dxkit/reports/` with a date-stamped filename:
+
+```
+.dxkit/reports/
+  health-2026-05-19.md
+  health-2026-05-19.json
+  vulnerability-scan-2026-05-19.md
+  vulnerability-scan-2026-05-19-detailed.json
+  ...
+  dashboard.html
+```
+
+The `.md` files are human-readable; the `.json` files are machine-readable (for CI consumption or custom tooling). Reports are gitignored by default — they regenerate on every run.
+
+## Reading the health report
+
+The 6 dimensions each get an A-E grade. Below each grade the "top actions" list shows what would lift the score the most (sorted by potential uplift). Example:
+
+```
+Security: B (72)
+  Top actions:
+    1. Pin @types/node to ≥18.19.0 (closes 2 dep-vuln entries)
+    2. Add gitleaks pre-commit hook (closes 1 secret-scan finding)
+    3. Replace `Math.random()` in src/auth/token.ts (closes 1 SAST finding)
+```
+
+Score → rating: A ≥ 80, B ≥ 60, C ≥ 40, D ≥ 20, E < 20. **Cap tiers** can pin a score below its arithmetic value when trust is broken (e.g., uncommitted state caps at 79). The report explains the cap if one fires.
+
+## Common patterns
+
+### Quick health check (warm cache)
+
+```bash
+vyuh-dxkit health
+```
+
+Re-uses cached scanner outputs where possible. ~5-15s on warm cache, ~30-60s cold.
+
+### Pre-merge audit (thorough)
+
+```bash
+vyuh-dxkit health --with-coverage   # Runs tests + materializes coverage before scoring
+vyuh-dxkit vulnerabilities          # Always re-runs the deep security scan
+vyuh-dxkit dashboard                 # Renders the latest reports into one HTML view
+```
+
+`--with-coverage` is slow (runs your test suite) but switches the Tests dimension from heuristic ("files match a test pattern") to real ("line coverage from your reporter"). Worth it for pre-merge audits.
+
+### Per-PR scope
+
+```bash
+vyuh-dxkit guardrail check
+```
+
+Diffs the current scan vs the baseline. Exit 1 on net-new findings (the same logic the pre-push hook uses).
+
+### Failing CI on a threshold
+
+```bash
+vyuh-dxkit health --fail-on-score=70                 # Exit 1 if overall score < 70
+vyuh-dxkit vulnerabilities --fail-on-severity=high   # Exit 1 if any high-severity finding
+```
+
+Use these in CI for hard floors.
+
+## Reading dependency findings
+
+`vulnerabilities` (and `bom`) carry severity + CVSS where available. The severity column is computed via OSV.dev's enrichment — when OSV reports no severity, dxkit assigns one via CVSS v4.0 base-score math (see `src/analyzers/tools/cvss-v4.ts`).
+
+When the user asks "is this CVE worth fixing today" the answer depends on:
+1. **Reachability** — does the codebase actually call the vulnerable function? (Today: heuristic via graphify call-graph; reachability tiers are a roadmap item.)
+2. **Exploitability** — public PoC? Authentication required? Network exposure?
+3. **Patch availability** — is there a fixed version?
+
+Surface those three when summarizing a dep-vuln finding. The detailed JSON has the OSV/GHSA reference URL — link to it.
+
+## When the user wants to ACT on findings
+
+Hand off to the `dxkit-action` skill — that's the workflow for prioritizing + fixing + re-baselining. This skill stops at "here's what's wrong."
+
+## Troubleshooting
+
+- **"Scanner X unavailable"** → run `vyuh-dxkit tools list` to see status; `vyuh-dxkit tools install` to install missing ones.
+- **"N/A for this stack"** → applicability-guard fired (e.g., vitest-coverage on a mocha repo). Not a problem; the scanner doesn't apply here.
+- **Report looks stale** → `.dxkit/reports/` is keyed by date. Re-run the analyzer to get a fresh date-stamped file.
+- **Numbers don't match between two reports** → check whether `--with-coverage` was used. Without it, Tests dimension uses heuristic; with it, real coverage. They legitimately differ.

package/templates/.devcontainer/devcontainer.json

@@ -0,0 +1,55 @@
+{
+  "name": "dxkit dev environment",
+
+  // Universal base + per-stack composable features. The features
+  // block below is generated by `vyuh-dxkit init` from the detected
+  // stack — only toolchains your project actually uses get installed.
+  // Always-on: Node (dxkit's own runtime) + GitHub CLI. Add or
+  // remove entries by hand if you want to over- or under-ride the
+  // auto-detected set.
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
+
+  "features": __DXKIT_DEVCONTAINER_FEATURES__,
+
+  // Reproducibility note: language toolchains are pinned in the
+  // features block above. Scanner tools (gitleaks, semgrep, cloc,
+  // jscpd, ruff, osv-scanner, ...) are pinned in dxkit's TOOL_DEFS
+  // registry and installed by `vyuh-dxkit tools install --yes` in
+  // post-create.sh. Bumping a scanner version is a dxkit upgrade,
+  // not a Dockerfile edit.
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+
+  // Run on every container start (incl. Codespaces resume). Keeps
+  // `dxkit tools list` accurate if a tool was uninstalled or the
+  // registry pinned-versions advanced since last use.
+  "postStartCommand": "command -v vyuh-dxkit >/dev/null 2>&1 && vyuh-dxkit tools list || true",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "golang.go",
+        "rust-lang.rust-analyzer",
+        "ms-dotnettools.csharp",
+        "redhat.java",
+        "fwcd.kotlin",
+        "rebornix.ruby",
+        "github.vscode-github-actions",
+        "github.vscode-pull-request-github"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "files.eol": "\n"
+      }
+    }
+  },
+
+  "remoteUser": "vscode",
+
+  // Forward dxkit's HTTP analyzer dashboard if you run it locally.
+  "forwardPorts": []
+}

package/templates/.devcontainer/install-agent-clis.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# Install the AI coding-agent CLIs that pair with dxkit's commit-time
+# guardrails. Pinned versions so devcontainer rebuilds produce a
+# deterministic environment; bump these intentionally.
+#
+# Both CLIs are published to npm and install globally into the
+# devcontainer image's Node toolchain (provided by the features
+# block in devcontainer.json).
+
+set -euo pipefail
+
+# Pinned at devcontainer template publish time. Loosen to `@latest`
+# if you want each container start to pull the newest CLI — at the
+# cost of non-deterministic builds. Set to `skip` to skip the install
+# entirely (useful if you only use one of the two agents).
+CLAUDE_CODE_VERSION="${CLAUDE_CODE_VERSION:-latest}"
+CODEX_VERSION="${CODEX_VERSION:-latest}"
+
+if [ "${CLAUDE_CODE_VERSION}" = "skip" ]; then
+  echo "==> Claude Code CLI install skipped (CLAUDE_CODE_VERSION=skip)."
+else
+  echo "==> Installing Claude Code CLI..."
+  if command -v claude >/dev/null 2>&1; then
+    echo "    Already installed: $(claude --version 2>&1 | head -n1)"
+  else
+    npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
+      || echo "WARN: Claude Code install failed — try manually with 'npm install -g @anthropic-ai/claude-code'." >&2
+  fi
+fi
+
+if [ "${CODEX_VERSION}" = "skip" ]; then
+  echo "==> OpenAI Codex CLI install skipped (CODEX_VERSION=skip)."
+else
+  echo "==> Installing OpenAI Codex CLI..."
+  if command -v codex >/dev/null 2>&1; then
+    echo "    Already installed: $(codex --version 2>&1 | head -n1)"
+  else
+    npm install -g "@openai/codex@${CODEX_VERSION}" \
+      || echo "WARN: Codex CLI install failed — try manually with 'npm install -g @openai/codex'." >&2
+  fi
+fi

package/templates/.devcontainer/post-create.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# Devcontainer post-create. Runs once after the container is built
+# (and again on Codespaces prebuild). Idempotent — safe to re-run.
+#
+# Responsibilities:
+#   1. Install project dependencies if this is a Node project.
+#   2. Ensure dxkit is on PATH (project-local first, global fallback).
+#   3. Install dxkit's scanner toolchain (gitleaks, semgrep, cloc, etc.)
+#      via the TOOL_DEFS registry — pinned versions, language-aware.
+#   4. Install the AI coding-agent CLIs for the AI-native dev loop.
+#
+# Run from the repo root — the devcontainer's workspaceFolder is set
+# by `devcontainer.json` so the post-create command starts there.
+
+set -euo pipefail
+
+echo "==> dxkit post-create starting in $(pwd)"
+
+# Install project dependencies if this is a Node project. Soft-fail
+# the whole step: a lockfile that won't resolve (tarball moved,
+# private-registry auth not configured yet, peer-dep churn) is
+# annoying but shouldn't take down the rest of the post-create. The
+# user can re-run `npm install` after authenticating or fixing the
+# lockfile.
+#
+# The fallback chain layers three install strategies before giving up:
+#
+#   1. `npm ci` (lockfile path only) — strict, fast, uses the lockfile
+#      verbatim. Happy path on a healthy tree.
+#   2. `npm install` — looser; rebuilds lockfile entries if the
+#      lockfile drifted (lockfile vs package.json mismatch after a
+#      merge, for example).
+#   3. `npm install --legacy-peer-deps` — last resort. npm v7+ defaults
+#      to strict peer-dep resolution; brownfield monorepos almost
+#      always carry unresolved peers (eslint 8↔10, react cross-pkg
+#      peer mismatches, etc.) which fail both prior steps with
+#      multi-line ERESOLVE dumps. Legacy mode skips the peer-dep
+#      check and gets a working node_modules/.
+if [ -f package.json ]; then
+  echo "==> Installing project dependencies..."
+  if [ -f package-lock.json ]; then
+    npm ci || npm install || npm install --legacy-peer-deps || {
+      echo "WARN: project dependency install failed even with --legacy-peer-deps — re-run 'npm install --legacy-peer-deps' manually after fixing the cause." >&2
+    }
+  else
+    npm install || npm install --legacy-peer-deps || {
+      echo "WARN: project dependency install failed even with --legacy-peer-deps — re-run 'npm install --legacy-peer-deps' manually after fixing the cause." >&2
+    }
+  fi
+fi
+
+# Resolve dxkit. Prefer the project-local install if a `package.json`
+# pinned dxkit in devDependencies; otherwise install globally so the
+# binary is on PATH for the rest of the script and any subshell.
+if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "==> Installing @vyuhlabs/dxkit globally..."
+  npm install -g @vyuhlabs/dxkit
+  DXKIT="vyuh-dxkit"
+fi
+echo "==> Using dxkit binary: ${DXKIT}"
+
+echo "==> Installing scanner toolchain via dxkit registry..."
+# `tools install --yes` reads the detector's required-tools list and
+# runs the pinned install command for each one. Tools already present
+# are no-ops, so this is fast on warm containers. Soft-fail so a
+# single tool's install hiccup doesn't break the whole container.
+"${DXKIT}" tools install --yes || {
+  echo "WARN: some scanner tools failed to install — run 'vyuh-dxkit tools list' to see status." >&2
+}
+
+echo "==> Installing AI coding-agent CLIs..."
+bash "$(dirname "$0")/install-agent-clis.sh" || {
+  echo "WARN: agent CLI install had issues — install manually if needed." >&2
+}
+
+echo "==> dxkit post-create done. Run 'vyuh-dxkit health' to verify."

package/templates/.githooks/pre-commit

@@ -0,0 +1,55 @@
+#!/usr/bin/env sh
+#
+# dxkit pre-commit hook — fast guardrail check against the baseline.
+#
+# Runs `vyuh-dxkit guardrail check --changed-only` so only findings
+# overlapping lines you just changed can block the commit. The full
+# guardrail (without --changed-only) runs in the pre-push hook and
+# in the CI PR-gate workflow; this one prioritises feedback speed.
+#
+# Install:
+#   git config core.hooksPath .githooks
+#
+# Escape hatches:
+#   DXKIT_SKIP_HOOKS=1 git commit ...     # one-off bypass
+#   git commit --no-verify ...            # standard git bypass
+#
+# First-time setup: this hook does NOT block when no baseline exists
+# yet. Run `vyuh-dxkit baseline create` once to capture today's state,
+# then commits start being gated against it.
+
+set -e
+
+if [ "${DXKIT_SKIP_HOOKS:-0}" = "1" ]; then
+  echo "[dxkit pre-commit] DXKIT_SKIP_HOOKS=1 set — skipping guardrail check."
+  exit 0
+fi
+
+# Resolve the dxkit binary: prefer the project-local install, fall
+# back to a global one. We deliberately do NOT shell out to `npx`
+# here — npx may try to fetch from the registry, which makes the
+# hook fail offline and slow down every commit.
+if [ -x "./node_modules/.bin/vyuh-dxkit" ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "[dxkit pre-commit] vyuh-dxkit not found on PATH or in ./node_modules/.bin." >&2
+  echo "  Install it with: npm install --save-dev @vyuhlabs/dxkit" >&2
+  echo "  Or skip this hook for this commit: DXKIT_SKIP_HOOKS=1 git commit ..." >&2
+  exit 1
+fi
+
+BASELINE_NAME="${DXKIT_BASELINE_NAME:-main}"
+BASELINE_FILE=".dxkit/baselines/${BASELINE_NAME}.json"
+
+if [ ! -f "${BASELINE_FILE}" ]; then
+  echo "[dxkit pre-commit] No baseline at ${BASELINE_FILE} — not blocking."
+  echo "  Run \`${DXKIT} baseline create\` once to start gating commits."
+  exit 0
+fi
+
+# `--changed-only` restricts blocking to findings whose anchor line
+# overlaps the diff between the baseline's anchor commit and HEAD.
+# Pre-commit is fast-mode by design; the pre-push hook runs full.
+"${DXKIT}" guardrail check --changed-only --name "${BASELINE_NAME}"

package/templates/.githooks/pre-push

@@ -0,0 +1,63 @@
+#!/usr/bin/env sh
+#
+# dxkit pre-push hook — full guardrail check against the baseline.
+#
+# Runs the full `vyuh-dxkit guardrail check` (no --changed-only),
+# so every regression introduced since the baseline blocks the push.
+# Slower than pre-commit, but the push boundary is the last point
+# we can stop bad code from leaving the developer's machine.
+#
+# Install:
+#   git config core.hooksPath .githooks
+#
+# Escape hatches:
+#   DXKIT_SKIP_HOOKS=1 git push ...       # one-off bypass
+#   git push --no-verify ...              # standard git bypass
+
+set -e
+
+if [ "${DXKIT_SKIP_HOOKS:-0}" = "1" ]; then
+  echo "[dxkit pre-push] DXKIT_SKIP_HOOKS=1 set — skipping guardrail check."
+  exit 0
+fi
+
+# Delete-only pushes (e.g. `git push origin --delete <branch>`) carry
+# no commits to gate. Git invokes pre-push with stdin lines of the
+# form: <local-ref> <local-sha> <remote-ref> <remote-sha>. A delete
+# has local-sha = 40 zeros. Skip rather than failing the gate on an
+# empty diff.
+all_zero=true
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+  if [ "${local_sha}" != "0000000000000000000000000000000000000000" ]; then
+    all_zero=false
+    break
+  fi
+done
+if [ "${all_zero}" = "true" ]; then
+  echo "[dxkit pre-push] Delete-only push detected — skipping guardrail check."
+  exit 0
+fi
+
+# Resolve the dxkit binary: prefer the project-local install, fall
+# back to a global one. Match the pre-commit hook's resolution order.
+if [ -x "./node_modules/.bin/vyuh-dxkit" ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "[dxkit pre-push] vyuh-dxkit not found on PATH or in ./node_modules/.bin." >&2
+  echo "  Install it with: npm install --save-dev @vyuhlabs/dxkit" >&2
+  echo "  Or skip this hook for this push: DXKIT_SKIP_HOOKS=1 git push ..." >&2
+  exit 1
+fi
+
+BASELINE_NAME="${DXKIT_BASELINE_NAME:-main}"
+BASELINE_FILE=".dxkit/baselines/${BASELINE_NAME}.json"
+
+if [ ! -f "${BASELINE_FILE}" ]; then
+  echo "[dxkit pre-push] No baseline at ${BASELINE_FILE} — not blocking."
+  echo "  Run \`${DXKIT} baseline create\` once to start gating pushes."
+  exit 0
+fi
+
+"${DXKIT}" guardrail check --name "${BASELINE_NAME}"

package/templates/.github/workflows/dxkit-baseline-refresh.yml

@@ -0,0 +1,78 @@
+name: dxkit baseline refresh
+
+# After every merge to main, regenerate `.dxkit/baselines/main.json`
+# to capture the new "approved" state of the repo. The next PR's
+# guardrail check is gated against this refreshed anchor, so a
+# regression introduced in PR N+1 stands out from the noise of
+# whatever was merged in PR N.
+#
+# The auto-commit carries `[skip ci]` so it doesn't re-trigger this
+# workflow or the guardrails PR-gate.
+
+on:
+  push:
+    branches: [__DXKIT_DEFAULT_BRANCH__]
+    # Ignore pushes that only changed the baseline file — those are
+    # this workflow's own commits, and re-running would be a no-op
+    # anyway. Belt-and-braces with [skip ci] below.
+    paths-ignore:
+      - '.dxkit/baselines/**'
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    # Don't re-run on our own auto-commit (defensive — paths-ignore
+    # above already filters the common case).
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          # `persist-credentials: true` (the default) leaves the
+          # token in .git/config so the final `git push` reuses it.
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install dxkit
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            npm install -g @vyuhlabs/dxkit
+          fi
+
+      - name: Install scanner tools
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            ./node_modules/.bin/vyuh-dxkit tools install --yes
+          else
+            vyuh-dxkit tools install --yes
+          fi
+
+      - name: Recompute baseline
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          "${DXKIT}" baseline create --force
+
+      - name: Commit and push refreshed baseline
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet -- .dxkit/baselines/; then
+            echo "Baseline unchanged — nothing to commit."
+            exit 0
+          fi
+          git add .dxkit/baselines/
+          git commit -m "chore(baseline): refresh main anchor [skip ci]"
+          git push

package/templates/.github/workflows/dxkit-guardrails.yml

@@ -0,0 +1,98 @@
+name: dxkit guardrails
+
+# Runs the dxkit guardrail check on every pull request. New regressions
+# vs. the committed `.dxkit/baselines/main.json` block the PR. Existing
+# findings (your "brownfield debt") are allowed — they were already
+# captured when you ran `vyuh-dxkit baseline create`.
+#
+# Customise by editing your project's `.dxkit/policy.json` (created by
+# `vyuh-dxkit init --with-ci`). The matcher's classifications
+# (added / relocated / tooling_drift / config_drift / persisted /
+# removed / fixed) map to block/warn buckets there.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  guardrail:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Full history so the git-aware matcher can resolve the
+          # baseline's anchor commit + diff against HEAD.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      # Install dxkit. Prefers a project-local install (devDependencies)
+      # so the version is pinned alongside the project. Falls back to a
+      # global install for non-JS projects.
+      - name: Install dxkit
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            npm install -g @vyuhlabs/dxkit
+          fi
+
+      # Install the scanner toolchain dxkit needs for this stack
+      # (gitleaks, semgrep, cloc, jscpd, ruff, osv-scanner, etc.).
+      # `--yes` makes the install non-interactive; the registry
+      # decides what to install based on detected languages.
+      - name: Install scanner tools
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            ./node_modules/.bin/vyuh-dxkit tools install --yes
+          else
+            vyuh-dxkit tools install --yes
+          fi
+
+      # Capture the markdown report regardless of exit code so we can
+      # post it as a PR comment even when the guardrail blocks.
+      - name: Run guardrail check
+        id: guardrail
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          set +e
+          "${DXKIT}" guardrail check --markdown > guardrail-report.md
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+
+      - name: Post PR comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          # Find a previous dxkit-guardrails comment by marker so we
+          # update in place rather than appending a new one per push.
+          MARKER='<!-- dxkit-guardrails -->'
+          {
+            printf '%s\n' "$MARKER"
+            cat guardrail-report.md
+          } > comment.md
+          existing=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+            --jq ".[] | select(.body | startswith(\"${MARKER}\")) | .id" \
+            | head -n1)
+          if [ -n "${existing}" ]; then
+            gh api -X PATCH \
+              "repos/${{ github.repository }}/issues/comments/${existing}" \
+              -F body=@comment.md
+          else
+            gh pr comment "${PR_NUMBER}" --body-file comment.md
+          fi
+
+      - name: Fail if guardrail blocked
+        run: exit ${{ steps.guardrail.outputs.exit_code }}