@vyuhlabs/dxkit 2.21.2 → 2.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "2.21.2",
+  "version": "2.23.0",
   "description": "A deterministic stop condition and code-graph context layer for AI coding agents: gives agents a code graph to make changes, then blocks only net-new detector-backed regressions at the stop boundary, with no model in the gate.",
   "license": "MIT",
   "author": "Vyuh Labs",

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

@@ -126,6 +126,20 @@ A repo running autonomous coding loops behind the dxkit Stop-gate has a **loop-o
 
 This key is read **only by the Stop-gate** (`vyuh-dxkit hook stop-gate`) — your CI / PR guardrail always uses the full policy above, so changing the loop posture never weakens your CI gate. Edit it here, or run `npx vyuh-dxkit init --claude-loop --loop-preset full-debt`. Use `full-debt` only when you deliberately want an unattended loop to also close test/quality gaps (it can drive a long repair). For setting up or operating the loop, hand off to the **dxkit-loop** skill.
 
+### Switching the flow-gate posture (`flow.mode`)
+
+The UI→API integration gate has its own posture under `flow.mode` in the same file:
+
+```jsonc
+{ "flow": { "mode": "warn" } }  // warn (default) | block | off
+```
+
+- `warn` — surface net-new broken integrations as warnings, never fail a build.
+- `block` — fail the check on an exact break (confidence-gated: only fully-specified bindings block).
+- `off` — the gate does not run.
+
+The gate is additive and fail-open: it only fires when a change touches a client call / route / spec, and self-skips when there is no served-side truth to check against. Set it up with `npx vyuh-dxkit init --flow`, or hand off to the **dxkit-flow** skill for setup / diagnosis / repair.
+
 ## Configuring deep-SAST ingestion (`.vyuh-dxkit.json:deepSast`)
 
 dxkit's bundled SAST is intraprocedural; interprocedural findings (path traversal, info exposure, SSRF, injection) come from an external engine (Snyk Code or CodeQL) ingested via the `dxkit-ingest` skill. Persist the engine + Snyk project once so `ingest --from-snyk` needs no flags:

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

@@ -18,6 +18,8 @@ The skill consumes `npx vyuh-dxkit doctor --json` output. Doctor returns a struc
 
 The skill iterates `summary.fixable[]`, asks the customer for confirmation on each fix (with the command shown), runs it, then re-runs doctor at the end to verify everything closed.
 
+Doctor also carries an optional top-level `flow` field when the repo has a UI→API surface — a diagnosis of the integration contract (unresolved client calls with reasons + suggestions, served routes nobody consumes, and how the served side is resolved). This is **diagnostic, not an install fix**: it does not appear in `summary.fixable[]`, and dxkit-fix leaves it alone. It surfaces contract health (e.g. a call to a route no backend serves) rather than a broken-install signal.
+
 ## The repair loop
 
 ```

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

@@ -0,0 +1,83 @@
+---
+name: dxkit-flow
+description: Configure, diagnose, and repair the dxkit UI→API integration gate — set up flow gating, explain the flow-contract diagnosis, fix a net-new broken integration a guardrail flagged, and run the cross-repo handshake. Use when the user says "set up the flow gate", "why is this call unresolved", "the guardrail says I broke an integration", "a route was removed but something still calls it", "wire up flow across repos", "publish the flow contract", or anything about the UI→API integration gate.
+---
+
+# dxkit-flow
+
+This skill owns the **UI→API integration gate**: dxkit statically reconstructs which client calls (`METHOD url`) bind to which server routes, and fails a PR that net-new breaks one — a frontend call to an endpoint no backend serves, or a removed route a consumer still calls.
+
+It is **thin orchestration over the deterministic CLI.** It never re-implements extraction: it runs `init` / `doctor` / `guardrail check` / `flow publish`, reads their structured output, and supplies judgment + code edits. The determinism stays in the CLI; the agent supplies the reasoning.
+
+## Modes
+
+Pick the mode from what the user is doing. They share context — a fix often starts from a diagnose.
+
+### setup — turn the gate on
+
+Flow setup is folded into `init`; **there is no `flow init` command.**
+
+- Fresh or re-run: `npx vyuh-dxkit init --flow` (forces `warn` posture, no prompt) or plain `npx vyuh-dxkit init` (interactive — it detects a UI→API surface and asks for the posture). If the repo has no client calls / routes, init stays silent; there is nothing to gate.
+- The posture lives in `.dxkit/policy.json:flow.mode`:
+  - `warn` — surfaces net-new breaks as warnings, never fails a build (the default; good for adoption).
+  - `block` — fails the check on an exact break (confidence-gated: only fully-specified bindings block).
+  - `off` — scaffold config only, do not gate.
+- To change it later, edit `flow.mode` (or defer to **dxkit-config**).
+
+### diagnose — read the contract's current state
+
+`doctor` carries the flow diagnosis; **there is no `flow doctor` command.**
+
+```
+npx vyuh-dxkit doctor --json   → read the top-level `flow` field
+```
+
+`flow` (when the repo has a UI→API surface) contains:
+- `topology` (monorepo / consumer-only / provider-only), `calls`, `routes`, `resolved`
+- `unresolved[]` — each `{ method, path, reason, suggestion, file, line }`. `reason` is `no-route` / `external` / `placeholder-only`; `suggestion` is `add-route` / `configure-participant` / `adopt-spec` / `annotate`.
+- `servedUnconsumed[]` — served routes no in-repo call hits (dead route, or a cross-repo consumer).
+- `connection.rung` — how the served side is resolved (`monorepo` / `committed-counterpart` / `configured-participants` / `unresolved`).
+
+Walk the `unresolved` tail and, per item, act on its `suggestion`: add the missing route, configure a participant (handshake mode), adopt a spec, or annotate an intentional external call.
+
+### fix — repair a net-new broken integration ⭐
+
+When a guardrail check (or the loop Stop-gate) reports a flow block, read it:
+
+```
+npx vyuh-dxkit guardrail check --json   → read `flowGate.findings[]`
+```
+
+Each finding is `{ method, path, file, line, reason, verdict }`. `reason` is `no-route` (a call to nothing) or `route-removed` (a served route the PR deleted, still consumed). For each:
+
+1. Explain it in one line: which call, which route, what the PR changed.
+2. Propose the **repair** — restore the removed route, update the consumer to the new route, or (only if genuinely intentional) add an explicit annotation / a per-finding allowlist entry that a human reviews.
+
+**Load-bearing safety rule — repair, never suppress.** Fix the integration; do not clear the block by refreshing the baseline or silently allowlisting the finding. An intentional break requires an explicit, reviewed acceptance, never a quiet re-baseline. This mirrors the loop discipline (do NOT refresh the baseline to clear a block) and is what keeps the gate honest when an agent is the one clearing it.
+
+### handshake — gate across repos
+
+When the provider a call targets lives in another repo, the gate needs that repo's served contract. Two ways, both landing in `.dxkit/flow/served.json` (which the gate reads offline):
+
+- **Committed counterpart** — the provider commits its own `served.json`; this repo vendors it. Fully offline, diff-reviewable.
+- **Workspace participants** — declare the services in `.dxkit/workspace.json` (`participants[]` with a local `path` and optional `ref`), then:
+
+  ```
+  npx vyuh-dxkit flow publish   → unions every participant's served routes into this repo's served.json
+  ```
+
+  `flow refresh` writes just this repo's snapshots; `flow publish` unions the whole mesh so this repo resolves calls to services it does not co-locate. Commit the result.
+
+## What lives where
+
+| Artifact | Role |
+|---|---|
+| `.dxkit/policy.json:flow` | posture (`mode`) + URL strip-prefixes + specs |
+| `.dxkit/workspace.json` | the participants (name, path, ref, base URLs) of a multi-repo system |
+| `.dxkit/flow/served.json` / `consumed.json` | the committed contract snapshots the gate reads |
+
+## Boundaries
+
+- WHETHER to gate + posture → this skill (setup) or **dxkit-config**.
+- A broken integration found during a PR → this skill (fix). If it surfaced through the loop Stop-gate, **dxkit-loop** explains the block; the repair is here.
+- Do not use this skill to re-extract flow by hand or to write CSVs — that is the CLI's job.

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

@@ -13,7 +13,7 @@ This skill handles the git-hook surface dxkit ships. Use it to install hooks, de
 
 `.githooks/pre-commit` (opt-in via `--with-precommit-hook`) — same guardrail check but on every commit. Slower on large repos (~1-3 min on 500+ file repos). Not in `--full` by default because the wall-clock cost gates adoption.
 
-Both run `npx vyuh-dxkit guardrail check`. The check exits 1 (blocking) on net-new findings vs. the baseline.
+Both run `npx vyuh-dxkit guardrail check`. The check exits 1 (blocking) on net-new findings vs. the baseline. The same check also runs the **flow integration gate** — a net-new broken UI→API integration (a call to an endpoint no backend serves, or a removed route a consumer still calls) blocks or warns per `.dxkit/policy.json:flow.mode`. To set up, diagnose, or repair that gate, hand off to the **dxkit-flow** skill.
 
 ## Installation
 

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

@@ -29,9 +29,14 @@ Ask the user what they want, then pick the right invocation:
 | `--with-baseline-refresh` | `.github/workflows/dxkit-baseline-refresh.yml` (post-merge regen) | Yes |
 | `--with-pr-review` | `.github/workflows/pr-review.yml` (AI PR review; needs `ANTHROPIC_API_KEY`) | No (still opt-in) |
 | `--claude-loop` | Stop-gate hook for autonomous loops (additive merge into `.claude/settings.json` + CLAUDE.md); implies the dxkit skills. Pair with `--loop-preset security-only\|full-debt` | No (opt-in — registers a hook that blocks the agent from stopping) |
+| `--flow` / `--no-flow` | Set up / suppress the UI→API integration gate. When `init` detects a UI→API surface it offers this automatically (interactive prompt for the posture); `--flow` forces it on with `warn`, `--no-flow` skips it. There is **no standalone `flow init`** — flow setup lives inside `init`. | Auto-offered when a UI→API surface is detected (silent otherwise) |
 
 `--yes` accepts all prompts; `--force` overwrites existing files instead of writing `.dxkit` sidecars on conflict.
 
+### The flow step (auto-detected)
+
+When `init` finds client HTTP calls and/or server routes, it offers the **integration gate**: a PR that breaks a UI→API binding (a call to an endpoint no backend serves, or a removed route a consumer still calls) fails the guardrail. Interactively it asks for the posture with a one-line description of each — `warn` (default, surfaces breaks without failing a build), `block` (fails on an exact break), `off` (scaffold config only). It also confirms the dominant base-URL helper to strip and any multiple backend services. On a repo with no UI→API surface (a library, a CLI) the step is silent. Re-run or adjust later with `init --flow`; tune the posture in `.dxkit/policy.json:flow.mode`.
+
 ## Steps
 
 1. **Detect the stack** before installing — let the user confirm:

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

@@ -31,6 +31,8 @@ Don't use when:
 ```
 [1] State check       → is dxkit installed? scaffold present? baseline captured? hooks active?
 [2] Install if needed → npm init @vyuhlabs/dxkit OR npx vyuh-dxkit init --full --yes
+                        (init auto-offers the UI→API integration gate when it
+                         detects client calls + routes — pick a posture then)
 [3] Doctor            → npx vyuh-dxkit doctor (parse summary.fixable[])
 [4] Fix gaps          → dispatch through dxkit-fix for each fixable signal
 [5] Capture baseline  → npx vyuh-dxkit baseline create (with explicit secrets-warning)

package/templates/.githooks/pre-push

@@ -51,6 +51,16 @@ else
   exit 1
 fi
 
+# Correctness floor (liveness) — does the change still compile + do the tests
+# it affects pass? This is independent of the baseline, so it runs even before
+# a baseline exists (a brand-new / greenfield repo still gets push-time
+# liveness). It is ADAPTIVE: on a repo that already runs its tests in CI it is
+# a no-op here (opt-in), and on a repo without a test-CI it runs by default.
+# A real failure blocks the push; a missing toolchain fail-opens (CI backstop).
+# Tune via .dxkit/policy.json correctness.surfaces.pre-push, DXKIT_FLOOR_PREPUSH,
+# or bypass everything with: git push --no-verify
+"${DXKIT}" floor check --surface pre-push
+
 BASELINE_NAME="${DXKIT_BASELINE_NAME:-main}"
 BASELINE_FILE=".dxkit/baselines/${BASELINE_NAME}.json"
 

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

@@ -81,6 +81,23 @@ jobs:
             echo "✓ dxkit guardrail passed — no net-new findings vs the baseline"
           fi
 
+      # Correctness floor (liveness) — full-scope: does the code compile + do
+      # the tests pass? Runs after the finding gate. ADAPTIVE: if this repo
+      # already runs its tests in its own CI workflow, this is a no-op here
+      # (opt-in). A missing language toolchain fail-opens (this workflow sets up
+      # node + the dxkit scanner tools, not every language runtime), so the
+      # floor is most meaningful on JS/TS repos and on repos with no test-CI;
+      # your own test job is the place for full-language coverage. Tune via
+      # .dxkit/policy.json correctness.surfaces.ci or DXKIT_FLOOR_CI.
+      - name: Run correctness floor
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          "${DXKIT}" floor check --surface ci
+
       - name: Post PR comment
         if: always()
         env: