From 99b41a62f61b912e068dfb941026bca265e1dab2 Mon Sep 17 00:00:00 2001 From: T3 Code PR Stack <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 28 Jul 2026 13:15:46 +0200 Subject: [PATCH] docs(agents): mandatory pre-push gate and per-layer full CI green Require full local verification (vp check, scoped typecheck, focused tests, lockfile) before every push, and require every stack layer's Fork CI jobs to pass before advancing to the next layer. --- AGENTS.md | 114 ++++++++++++++++++++++++++++++++++----------- docs/fork-stack.md | 26 +++++------ 2 files changed, 99 insertions(+), 41 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eb0645b1815..8ca399b5957 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,12 +85,12 @@ branches. like `ERR_PNPM_OUTDATED_LOCKFILE` / "specifiers in the lockfile don't match package.json". Prefer regenerating the lockfile over repeatedly choosing ours/theirs on `pnpm-lock.yaml` during multi-commit rebases of `fork/changes`. -- **Per-layer `vp check` after stack rebase (required):** when rebasing or rewriting the stack, - run root **`vp check` on each layer and fix all failures before rebasing the next layer**. Order: +- **Per-layer green before next layer (required):** when rebasing, rewriting, or composing the + stack, **every layer must be fully green before you advance**. That means local pre-push gates + **and** Fork CI (all jobs that apply to that ref) on that layer's tip — not “push and hope.” Order: `fork/tim` → `fork/candidates` → `fork/changes` → each overlay → compose `fork/integration`. - Do not push a "green later" tip and stack on top of it. Same rule for feature PRs after - `pnpm fork:stack update`: rebase, then `vp check`, then push/merge. Full detail: - [docs/fork-stack.md](./docs/fork-stack.md) ("Per-layer `vp check` after stack rebase"). + Do not stack work on a red tip. Full detail: [docs/fork-stack.md](./docs/fork-stack.md) + ("Per-layer green gate"). - **Conflict resolutions (required when stack hits conflicts):** do **not** only hand-resolve and resume. Update `.github/pr-stack.json` `conflictResolutions` so the next sync auto-applies the same side. Prefer durable `commit: "*"` + path policies; exact SHAs go stale after every rewrite. @@ -112,9 +112,8 @@ When implementation work for a user request is done (code, docs, config — not 2. **Open or update a PR against `fork/changes`** before handing off. Do not target `main` unless the change is intentionally an upstream-mirror / promote projection. 3. **Keep the PR mergeable** before saying “updated the PR” or finishing: - - Run the exact local **Check** gate (`vp check`), local package typechecks for the changed scope - (see Task Completion Requirements), and focused tests **before** push. Do not use Fork CI as - the first formatter, linter, or typechecker. + - Complete the **mandatory pre-push verification** (see Task Completion Requirements) — never + push knowing only “the tests I thought of” passed while check/typecheck were skipped. - `pnpm fork:stack update --push` (current branch) or `pnpm fork:stack update --push ` - Confirm with `gh pr view --json baseRefName,mergeable,mergeStateStatus,url` - `baseRefName` must be `fork/changes` for ordinary features or the intended parent branch for a @@ -139,26 +138,85 @@ If Discord turn context lists **Linked work items** / Jira issues for the thread ## Task Completion Requirements -- Keep local verification focused on the files and packages changed. Run the smallest relevant test set; do not run the full workspace test suite as a routine completion step. - - **Before every push / PR handoff, run `vp check` from the repository root.** This is the exact - formatter/linter gate used by Fork CI's **Check** job. A focused format or lint command is useful - while iterating but is not a substitute for this final gate. - - Use `vp test run ` for focused built-in Vite+ tests. Use `vp run test` only when the affected package specifically requires its `test` script. - - Backend changes must include and run focused tests for the changed behavior. - - **Before every push / PR handoff**, run **local** typecheck for every package whose types can break from the change (not “wait for CI”): - - Touched package scripts when available, e.g. `pnpm --filter @t3tools/client-runtime exec tsgo --noEmit`, `apps/web` → `tsgo --noEmit`, `apps/mobile` → `tsc --noEmit` (from package dir or via workspace filter). - - Prefer the package’s own typecheck binary over relying on Fork CI **Check** to discover import-extension, exactOptionalPropertyTypes, or cross-package errors. - - If `pnpm` prepare/hooks block `pnpm exec`, invoke the workspace binary directly (`node_modules/.bin/tsgo` / `tsc`) from the package directory. - - Run targeted formatting and lint for the affected scope when available. -- Do **not** treat CI as the first typecheck. CI remains the full-suite gate; agents must not open or update a PR knowing only unit tests passed while package typecheck was skipped. -- Do not run repo-wide `vp run typecheck`, `vp run test`, or equivalent full-suite typecheck/test - commands locally unless the user explicitly requests them. `vp check` is the required exception - and must run before every push / PR handoff. -- After frontend feature development or any user-visible frontend behavior change, the primary agent must run one integrated verification pass for each affected client surface after integrating the work: - - Web: use the `test-t3-app` skill. Launch one isolated environment, authenticate through the printed pairing URL, and verify the affected flow in the controlled browser. - - Mobile: use the `test-t3-mobile` skill. Connect one representative iOS Simulator or Android Emulator available on the host to one isolated environment and verify the affected flow. On compatible macOS hosts, prefer iOS for cross-platform changes and stream it through serve-sim in the T3 Code in-app browser or another available agent browser; use Android when it is the affected or viable platform. - - Subagents must not independently launch dev servers or repeat integrated client verification unless their delegated task explicitly requires it. - - Stop dev servers, watchers, and other long-running verification processes when the focused verification is complete. +### Mandatory pre-push verification (every push) + +**Before every `git push` / force-with-lease / PR open / PR update / stack layer push, complete the +full local gate below and fix failures.** Do not push red work “for CI to catch.” Fork CI is a +second line of defense, not the first typecheck or formatter. + +Run from the repository root on the commit you are about to push (after install/lockfile are +consistent with that tree): + +1. **Root Check gate (always):** `vp check` + Exact formatter/linter gate used by Fork CI **Check**. Focused format/lint while iterating is + fine; it is **not** a substitute for root `vp check` right before push. +2. **Package typecheck (always for touched scope):** run the package typecheck for **every** + package whose types can break from the change (import-extension, `exactOptionalPropertyTypes`, + cross-package consumers). Prefer package filters / binaries, e.g.: + - `pnpm --filter @t3tools/client-runtime exec tsgo --noEmit` + - `apps/web` → `tsgo --noEmit` (or workspace filter) + - `apps/mobile` → `tsc --noEmit` + - `apps/server` / package name `t3` → that package’s typecheck + - If `pnpm exec` is blocked by prepare hooks, use `node_modules/.bin/tsgo` / `tsc` from the + package directory. +3. **Focused tests (always when behavior/tests exist):** `vp test run ` for changed + behavior. Backend changes must include and run focused tests for the changed behavior. Use + `vp run test` only when that package’s `test` script is the right tool. +4. **Lockfile (when manifests or deps changed):** regenerate until frozen install would succeed + (`CI= pnpm install --no-frozen-lockfile` as needed) and commit a matching `pnpm-lock.yaml`. + +**Explicitly do not skip** check, typecheck, or focused tests to save time. **Do not** treat +“unit tests passed” as enough if typecheck was not run. + +**Heavy / optional (do not run as routine pre-push unless the user asks or the change requires it):** + +- Full-repo `vp run typecheck`, `vp run test`, or monorepo-wide test matrix +- Integrated browser/mobile verification (see below — required only for user-visible client changes) +- Long E2E, full mobile native suites, release packaging + +### After push: stack layers must be fully CI-green before the next layer + +When working the fork stack (rebase, rewrite, overlay update, compose, recovery): + +```text +main (mirror only) + → fork/tim + → fork/candidates + → fork/changes + → each overlay (desktop, discord, vscode) + → fork/integration (compose last) +``` + +**Rules (required):** + +1. Finish **local pre-push verification** on the layer tip, then push that layer. +2. **Wait for Fork CI on that layer’s tip to pass every applicable job** (Check, Test, and any + other jobs that run for that ref — not only a subset). Fix failures and re-push until green. +3. **Only then** rebase/update the next layer onto the green parent (or compose integration). +4. **Never** advance with “CI still running / red, fix later.” Cascading red layers is a process + failure. +5. Feature PRs: same local gate before every push; do not open/update a PR knowing typecheck or + `vp check` was skipped. + +Confirm CI with `gh run list` / `gh pr checks` / `gh run view` for the exact SHA you pushed. + +### Client verification (user-visible UI only) + +After frontend feature development or any user-visible frontend behavior change, the primary agent +must run one integrated verification pass for each affected client surface after integrating the +work: + +- Web: use the `test-t3-app` skill. Launch one isolated environment, authenticate through the + printed pairing URL, and verify the affected flow in the controlled browser. +- Mobile: use the `test-t3-mobile` skill. Connect one representative iOS Simulator or Android + Emulator available on the host to one isolated environment and verify the affected flow. On + compatible macOS hosts, prefer iOS for cross-platform changes and stream it through serve-sim in + the T3 Code in-app browser or another available agent browser; use Android when it is the + affected or viable platform. +- Subagents must not independently launch dev servers or repeat integrated client verification + unless their delegated task explicitly requires it. +- Stop dev servers, watchers, and other long-running verification processes when the focused + verification is complete. ## Dev Servers diff --git a/docs/fork-stack.md b/docs/fork-stack.md index 3da2070f866..39b02d56021 100644 --- a/docs/fork-stack.md +++ b/docs/fork-stack.md @@ -283,19 +283,19 @@ inherits a SOCKS proxy). Compose therefore: On btrfs/xfs same-filesystem copies this is CoW (seconds for multi‑GB trees). On other FS it falls back to a full copy. Optional: `COMPOSE_WORK_ROOT` overrides the work directory parent. -### Per-layer `vp check` after stack rebase (required) +### Per-layer green gate (required) -When you manually rebase or rewrite the stack, **do not advance to the next layer until the current -layer is clean**. After each layer is rebased onto its parent, install/lock is consistent, and -conflicts are resolved: +When you manually rebase, rewrite, or compose the stack, **do not advance to the next layer until +the current layer is fully green**. “Green” means: -1. Check out that layer's tip. -2. Run root **`vp check`** (the same formatter/linter gate Fork CI uses). -3. Fix every failure on **that layer** (format, lint, lockfile, type-level breakage the check - surfaces). Commit and force-with-lease push the layer if needed. -4. Only then rebase the **next** layer onto the fixed parent. +1. **Local pre-push gate** on that tip (see `AGENTS.md` Task Completion Requirements): root + `vp check`, package typechecks for the affected scope, focused tests, matching lockfile. +2. **Push** the layer tip. +3. **Fork CI on that exact tip passes every applicable job** (Check, Test, and any other jobs that + run for that ref). Do not proceed while CI is red, cancelled, or still running “for later.” +4. **Only then** rebase the next layer onto the green parent (or compose `fork/integration`). -Layer order for this gate: +Layer order: ```text main (upstream mirror — skip product fixes; do not hand-edit) @@ -306,9 +306,9 @@ main (upstream mirror — skip product fixes; do not hand-edit) → fork/integration (compose last) ``` -Skipping `vp check` and stacking "fix it later" commits is how lockfile and lint failures cascade -into every PR and block merge. Feature PRs (e.g. based on `fork/changes`) get the same treatment -after `pnpm fork:stack update`: rebase onto the fixed parent, then `vp check` before push/merge. +Skipping local gates or stacking on a red tip is how lockfile, typecheck, and lint failures cascade +into every PR and block deploy. Feature PRs after `pnpm fork:stack update` use the same local +pre-push gate before every push. `register` is used during the one-time cutover and only when intentionally building an advanced, dependent integration chain: