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

docs: distinguish focused pregate from full release validation

[._.]/ Adam Eivyf8a466768ce2
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 987f526900..055918bf1c 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -294,8 +294,9 @@ unloaded machine, so a concurrent run can time out cases a sequential run
passes.
For the intermittent synthetic gallery-page timeout investigation (#13369),
-`PORTOS_DB_PHASE_DIAGNOSTICS=1 npm run pregate` adds wall/CPU timings for fixture
-construction, seeding, public calls, EXPLAINs and result serialization. To obtain
+`PORTOS_DB_PHASE_DIAGNOSTICS=1 npm run pregate -- --full` adds wall/CPU timings
+for fixture construction, seeding, public calls, EXPLAINs and result
+serialization when the plan selects the DB suite. To obtain
the complete serial DB workload regardless of test-memo reuse, run
`PORTOS_DB_PHASE_DIAGNOSTICS=1 npm run test:db` after the earlier validation
stages finish. The observer reads only `portos_test` session state, waits,
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index 7d6fd66c8d..88a97cfac1 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -171,15 +171,17 @@ 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: hidden-content scan, early server and client structural guards, 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
+diff and hands its plan to the same runners. Default `npm run pregate` runs the
+hidden-content scan, early server and client structural guards, lint, and
+focused unit tests: edited test files and sibling tests for changed sources,
+including untracked tests, without expanding through transitive imports.
+
+`npm run pregate -- --full` opts into the CI-selected broad suites locally:
+server and client tests, the client build and its API Explorer bundle pin, the
+boot smoke, 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 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