Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Document what the local gate now runs and the receipt it leaves

[._.]/ Adam Eivy1fce24493272
diff --git a/AGENTS.md b/AGENTS.md
index be82c39651..49e96fda15 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,12 +55,12 @@ npm test --prefix client # Vitest (happy-dom) — component/unit tests
# inherits it aims at the real Postgres.
npm run test:db # DB-backed suites → portos_test ONLY (see Security Model)
-npm run pregate # BEFORE EVERY PUSH — local CI-plan checks; limits below
+npm run pregate # BEFORE EVERY PUSH — CI's plan run locally; receipt in .cache/pregate/report.json
```
**Run `npm run pregate` before every push and again after rebasing onto a moved base.** It uses CI's planner and runners, including tree-wide guards for import boundaries, catalog merges, and generated manifests. The local plan includes both committed and uncommitted changes, including untracked files.
-A full-suite plan runs only the always-run guards unless `--full` is supplied. DB suites, Windows, client build, and boot smoke are reported but not run by pregate. A green pregate proves only the stages it ran; required CI checks still apply.
+A scoped plan runs every suite it selects, in CI's order and with CI's environment: lint, server and client tests, the client build and its bundle pin, the boot smoke, the browser suites, and the serial `portos_test` DB suite last and alone (it is pinned to `portos_test` and can never target `portos`). A full-suite plan runs only the always-run guards unless `--full` is supplied, which runs everything. A suite left to CI — by `--skip-db`, `--skip-browser`, `--skip-build`, `--skip-smoke`, by the downgrade, or because the machine lacks a prerequisite (a reachable test Postgres; Chrome, ffmpeg and the client bundler) — is named as not run in the summary and in the receipt `.cache/pregate/report.json` (plan, stage outcomes and durations, base and HEAD SHAs, and the hash of the exact working tree validated, uncommitted and untracked files included). The shipped prompt-history guard runs locally when the planner selects it. A green pregate proves only the stages it ran; the Windows job and the Linux worker-containment job are the two only CI can prove, and required CI checks still apply.
## Test Strategy: Value Over Assertion Count
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index e8dddfd99e..0d94a808b4 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -89,7 +89,36 @@ See [VERSIONING.md](./VERSIONING.md) for full details.
Pregate first checks installed package versions against all four workspace lockfiles without modifying dependency trees. Stale, missing, or unreadable evidence stops lint/tests with a reconciliation diagnostic. Pregate requires development dependencies (`npm ci --include=dev` in an owning workspace); a production-only installation cannot run its checks. Ordinary worktree links must be repaired only in their owning source checkout; a separate clone with its own locked installs is also suitable for validation. `--plan-only` prints the plan without checking installed dependencies.
-Pregate proves only the stages it runs; it does not replace required CI or resource-dependent checks. A full-suite plan runs only the always-run guards unless `--full` is supplied; DB suites, Windows, client build, and boot smoke are reported but not run by pregate.
+Pregate proves only the stages it runs, and it says which it did not. A scoped
+plan runs every suite CI would run for it, in CI's dependency order and with
+CI's environment: the hidden-content scan, lint, server and client tests, the
+client build plus the API Explorer bundle pin, the boot smoke, the
+cross-workspace browser suites (smoke profile), and the serial `portos_test`
+DB suite last and alone — never concurrently with the other suites, and never
+against `portos` (both `PGDATABASE` and `PGTESTDATABASE` are pinned and
+`TEST_DB_OK` is removed from the stage's environment). A full-suite plan runs
+only the always-run guards unless `--full` is supplied, which runs everything
+above as well.
+
+A suite stays with CI, and is named as not run in the summary, when:
+
+- you pass `--skip-db`, `--skip-browser`, `--skip-build` or `--skip-smoke`;
+- a full plan was downgraded (no `--full`);
+- a prerequisite is missing — no Postgres answering at the resolved endpoint
+ (exported `PG*`, then the checkout's `.env`, then `localhost:5432`), or no
+ Chrome, ffmpeg or client bundler for the browser suites. The line names the
+ remedy; the run continues.
+
+The shipped prompt-history guard (CI's `prompt-history` job) runs locally
+when the planner selects it. The Windows job and the Linux worker-containment
+job (bubblewrap namespaces) are the two suites only CI can prove; both are
+named as not run. Every run writes a receipt to
+`.cache/pregate/report.json` (gitignored): the plan, each stage's outcome and
+duration, the suites not run and why, the base and HEAD SHAs, the Node
+version, platform and worker budget, and the hash of the exact working tree
+that was validated — untracked and uncommitted files included, so a later
+commit of that state yields the same `HEAD^{tree}`. A green summary never
+claims a suite it skipped; required CI checks still apply.
PRs run the browser suites' smoke profile; the `[fidelity]` cases run nightly
and on the release PR. To check them on a rendering PR before merging, run
@@ -209,7 +238,9 @@ PORTOS_PREGATE_MAX_WORKERS=4 npm test
npm test --prefix server -- services/creativeDirector/videoAssembly.test.js
```
-For release validation, run `npm run test:db` after the server and client
+`npm run pregate` runs the DB suite itself when the plan selects it, after
+every other stage, against `portos_test` only. For release validation by
+hand, run `npm run test:db` after the server and client
suites finish rather than alongside them. A concurrent run is supported —
the database restore suite drains a timed-out case before the next one touches
`portos_test` — but its per-case budgets assume an
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index 5663f2f4c4..b1b3114473 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -166,6 +166,25 @@ the job instead of silently skipping if the submodule still isn't there
(`CI_EXPECT_SLASHDO_SUBMODULE`); outside that signal — a local checkout, or a
CI run that never needed it — they keep the documented skip.
+### Local equivalent: `npm run pregate`
+
+`scripts/pregate.js` runs the same planner over the committed and uncommitted
+diff and hands its plan to the same runners, so a scoped plan is reproduced
+locally stage for stage: hidden-content scan, lint, server and client tests,
+the client build and its API Explorer bundle pin, the boot smoke, the browser
+suites (smoke profile, prerequisites required rather than skipped), and the
+serial `portos_test` DB suite last and alone. Each stage receives the
+environment the matching job sets. A full plan runs only the always-run guards
+unless `--full` is passed. A suite the machine cannot run (no reachable test
+Postgres; no Chrome, ffmpeg or client bundler), or one left to CI with
+`--skip-db`, `--skip-browser`, `--skip-build` or `--skip-smoke`, is reported
+as not run — in the summary and in the receipt `.cache/pregate/report.json`,
+which records the plan, stage outcomes and durations, the skipped suites, the
+base and HEAD SHAs, and the hash of the exact working tree validated. The
+shipped prompt-history guard runs locally when selected; the Windows job and
+the Linux worker-containment job are the two suites only CI can prove. Details and the receipt
+contract: `docs/CONTRIBUTING.md`.
+
### Vitest runner tuning
On GitHub Actions, `CI=true` caps the server Vitest runner at `maxWorkers: 4`
@@ -691,7 +710,8 @@ traversal to 57 explicit selectors and a ~941-file, ~40-minute local run
because `MAX_TARGETED_TEST_FILES` counts only explicit selectors. It now plans
full (Windows escalates, since the module owns cross-platform worktree
lifecycle). Default `npm run pregate` therefore runs only its always-run guards
-for it, `--full` runs everything, and CI runs the full sharded suite. Its test
+for it, `--full` runs everything (the build, smoke, browser and DB suites
+included), and CI runs the full sharded suite. Its test
file alone stays scoped; the #9673 consumer traversal is unchanged elsewhere.
Three properties keep that safe, each pinned by `scripts/ci-test-plan.test.js`: