feat(tooling): agent ship gate with draft-free push and pr:ready

Adopt scanner-style husky hooks, lint-staged, and pnpm pr:ready so agents
can push freely on drafts, validate once via the ship gate on publish or
ready-PR pushes, and cannot undraft with raw gh pr ready.

Rebased onto fork/changes and applied the ship-gate model across the fork's
AGENTS.md: publish validation runs through the automated gate (pre-push on
ready PRs / pnpm pr:ready), with per-layer stack CI kept as the explicit
protected-branch exception. Pre-commit now runs format + lint (typecheck and
tests stay in the ship gate). Node builtins in the new scripts follow the
fork's namespace-import convention.

Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>

Author: 2 people

.envrc

@@ -0,0 +1,3 @@
+# Prefer the repo gh policy shim so coding agents cannot undraft with raw
+# `gh pr ready` (use `pnpm pr:ready`). Installed by scripts/install-git-hooks.mjs.
+PATH_add .tools/bin

.gitignore

@@ -40,3 +40,9 @@ node_modules/
 *.log
 .env*
 !.env.example
+!.envrc
+# direnv
+.direnv
+# agent gh shim + local run state (ship-gate cache, etc.)
+.tools/
+.run/

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint-staged

.husky/pre-push

@@ -0,0 +1,7 @@
+# Agent-only ship gate (humans: no-op). See scripts/agent-pre-push.mjs.
+# Draft / no PR: free agent push. Ready PR: vp check + typecheck + tests.
+# Publish: pnpm pr:ready (not raw gh pr ready). Agent gh shim: .tools/bin/gh.
+#
+# Humans: SKIP_AGENT_PREPUSH=1 git push
+# Agents: never SKIP_AGENT_PREPUSH / never --no-verify
+pnpm exec node scripts/agent-pre-push.mjs

AGENTS.md

@@ -58,6 +58,15 @@ authenticated.
 - `vp run typecheck`: Strict TypeScript checks for all packages.
 - `vp run test`: Runs workspace tests.
 - `vp run lint:mobile`: Mobile native static analysis (`scripts/mobile-native-static-check.ts`).
+- `pnpm pr:ready`: Agent publish path — runs the ship gate (`vp check`, `vpr typecheck`,
+  `vp run test`), then marks the open draft PR ready. Do not use raw `gh pr ready` from coding
+  agents; the `.tools/bin/gh` shim blocks undraft side channels (installed by
+  `scripts/install-git-hooks.mjs` on `prepare`).
+- `pnpm test:agent-gate`: Unit tests for the agent pre-push / PR-state / gh-policy helpers.
+- Husky: `pre-commit` runs `pnpm lint-staged` (`vp fmt` on staged files + `vp lint --fix` on staged
+  code files);
+  `pre-push` runs `scripts/agent-pre-push.mjs` (agents only: free push on draft / no PR; full ship
+  gate on ready PRs; SHA cache in `.run/agent-ship-gate.json`).
 - `node apps/server/scripts/t3-sqlite-state.ts <query|exec> --base-dir <path> ...`: Inspects or seeds
   an isolated T3 SQLite database; writes create a private backup first.
 

docs/internals/scripts.md

@@ -0,0 +1,11 @@
+/** @type {import("lint-staged").Configuration} */
+export default {
+  // Keep in sync with vite.config.ts `staged`.
+  // Commit runs format + lint; the heavier typecheck + tests stay in the agent
+  // ship gate (pre-push on ready PRs / `pnpm pr:ready`).
+  // `--no-error-on-unmatched-pattern`: a commit whose staged files are all
+  // unformattable (e.g. only *.nix) must not fail pre-commit.
+  "*": "vp fmt --no-error-on-unmatched-pattern",
+  // Lint (with autofix) only the code files oxlint understands.
+  "*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}": "vp lint --fix",
+};

lint-staged.config.js

@@ -3,7 +3,9 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "prepare": "node scripts/clean-tsgo-backups.mjs && effect-tsgo patch && vp config --no-agent",
+    "prepare": "node scripts/clean-tsgo-backups.mjs && effect-tsgo patch && vp config --no-agent && node scripts/install-git-hooks.mjs",
+    "pr:ready": "node scripts/agent-pr-ready.mjs",
+    "test:agent-gate": "vp test run scripts/agent-pre-push.test.mjs",
     "dev": "node scripts/dev-runner.ts dev",
     "dev:share": "node scripts/dev-runner.ts dev --share",
     "dev:server": "node scripts/dev-runner.ts dev:server",
@@ -55,6 +57,8 @@
     "@oxlint/plugins": "^1.63.0",
     "@types/node": "catalog:",
     "@typescript/native-preview": "catalog:",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
     "vite-plus": "catalog:"
   },
   "engines": {

package.json

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Agent-facing `gh` policy shim.
+ *
+ * Installed at `.tools/bin/gh` by `scripts/install-git-hooks.mjs`.
+ * When coding-agent env markers are set, blocks undraft side channels
+ * (`gh pr ready`, ready_for_review API). Use `pnpm pr:ready` instead
+ * (sets AGENT_PR_SHIP=1 for the real call).
+ *
+ * Humans / non-agents: transparent pass-through to the next `gh` on PATH.
+ */
+import * as NodeChildProcess from "node:child_process";
+import * as NodePath from "node:path";
+import * as NodeProcess from "node:process";
+import * as NodeURL from "node:url";
+import { isCodingAgent } from "./lib/agent-env.mjs";
+import { findRealGh, inspectAgentGhCommand } from "./lib/agent-gh-policy.mjs";
+
+const selfPath = NodeURL.fileURLToPath(import.meta.url);
+const argv = NodeProcess.argv.slice(2);
+
+if (isCodingAgent()) {
+  const decision = inspectAgentGhCommand(argv);
+  if (decision.blocked) {
+    console.error(`agent gh: blocked: ${decision.reason}`);
+    NodeProcess.exit(1);
+  }
+}
+
+const realGh = findRealGh({ selfPath });
+if (!realGh) {
+  console.error("agent gh: could not resolve real `gh` binary (set AGENT_GH_REAL)");
+  NodeProcess.exit(127);
+}
+
+// Avoid re-entering this shim if PATH still prefers us.
+const env = { ...NodeProcess.env };
+const toolsBin = NodePath.resolve(NodePath.dirname(selfPath), "..", ".tools", "bin");
+const pathParts = (env["PATH"] ?? "").split(NodePath.delimiter).filter(Boolean);
+env["PATH"] = pathParts.filter((p) => NodePath.resolve(p) !== toolsBin).join(NodePath.delimiter);
+env["AGENT_GH_REAL"] = realGh;
+
+const result = NodeChildProcess.spawnSync(realGh, argv, {
+  stdio: "inherit",
+  env,
+  shell: false,
+});
+NodeProcess.exit(result.status === null ? 1 : result.status);