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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Document the pregate attestation and index the merge gate plan
[._.]/ Adam Eivy4ab6c5e3629b
diff --git a/AGENTS.md b/AGENTS.mdindex 8ceb143815..d685a075ef 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -58,11 +58,13 @@ npm run test:db # DB-backed suites → portos_test ONLY (see Senpm run pregate # BEFORE EVERY PUSH — CI's plan run locally; receipt in .cache/pregate/report.json# pregate and CI skip test files whose every input already passed (the test# memo, docs/GITHUB_ACTIONS.md "Test memo"); PORTOS_TEST_MEMO=off runs them all.+node scripts/pregate-attest.js # AFTER the push: posts the green receipt as a `pregate` commit status bound to the+ # validated tree so the PR's CI skips the attested stages; a refusal means full CI as before```**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 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.+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. After the push, `node scripts/pregate-attest.js` posts the receipt as a `pregate` commit status on the head; the pull request's planner skips the attested stages for same-repository heads the repository owner attested (`docs/GITHUB_ACTIONS.md` "Pregate attestation"). It refuses when the receipt is not green, the tree changed after pregate, or the commit is not pushed — report the refusal and let CI run everything; never rerun pregate only to attest.## Test Strategy: Value Over Assertion Countdiff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.mdindex c86c91831a..d46d6c60d9 100644--- a/docs/CONTRIBUTING.md+++ b/docs/CONTRIBUTING.md@@ -120,6 +120,18 @@ that was validated — untracked and uncommitted files included, so a latercommit of that state yields the same `HEAD^{tree}`. A green summary neverclaims a suite it skipped; required CI checks still apply.+After the push, `node scripts/pregate-attest.js` posts that receipt as a+`pregate` commit status on the pushed head, bound to the validated tree, and+the pull request's impact planner skips the stages it attests to (only stages+that ran and passed; never Windows, Linux containment or the Node-minimum+check). It refuses — saying what to rerun — when the receipt did not pass,+the tree changed after pregate, the commit is not on the upstream remote yet,+or nothing attestable ran; a refusal just means CI runs everything as before.+`--dry-run` prints the status without posting it. Only a repository writer+can create the status and only the repository owner's counts, so fork and+Dependabot pull requests are unaffected. Contract and inspection:+[Pregate attestation](GITHUB_ACTIONS.md#pregate-attestation).+PRs run the browser suites' smoke profile; the `[fidelity]` cases run nightlyand on the release PR. To check them on a rendering PR before merging, run`node scripts/browser-fidelity.js --pr NUMBER` from the clean published head. See@@ -264,7 +276,9 @@ state are never memoized. `PORTOS_TEST_MEMO=off` disables it, and[GITHUB_ACTIONS.md](./GITHUB_ACTIONS.md#test-memo).Pull requests into `main` run the tests for affected feature directories, with-conservative fallbacks to the runner's related-test mode or the complete suite. The+conservative fallbacks to the runner's related-test mode or the complete suite; a+same-repository pull request whose pushed head carries a pregate attestation+skips the stages that receipt proved (see the Git Workflow section). Thepull request into `release`, nightly CI, and manual CI runs always run thecomplete server, client, DB, lint, build, and smoke checks. Pushes to `main`run nothing — the pull request gate already covered that tree. Releasediff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.mdindex 73828b4bbf..9d00e60ef0 100644--- a/docs/GITHUB_ACTIONS.md+++ b/docs/GITHUB_ACTIONS.md@@ -185,6 +185,65 @@ shipped prompt-history guard runs locally when selected; the Windows job andthe Linux worker-containment job are the two suites only CI can prove. Details and the receiptcontract: `docs/CONTRIBUTING.md`.+### Pregate attestation++A green pregate on this machine runs the same planner, runners, environment+and `portos_test` database the Linux jobs do, so repeating those stages in CI+for the install's own pull requests buys queue time and nothing else (design+record: `docs/plans/2026-10-18-ci-local-first-merge-gate.md`). After the push,+`node scripts/pregate-attest.js` turns the receipt into a commit status on the+pushed head, and the impact planner skips what it attests to:++- **What is attested.** Only receipt stages that ran and passed: the+ hidden-content scan, lint, server and client tests, the client build and its+ bundle pin, the boot smoke, the browser suites and the DB suite, and the+ shipped prompt-history guard. A suite pregate reported as not run — skipped+ by a `--skip-*` flag, left to CI by a downgraded full plan, or missing a+ prerequisite — is not attested, and a downgraded full plan never attests+ its server or client stage (it ran the always-run guards, not CI's+ selection). The vocabulary is `ATTESTABLE_STAGES` in+ `scripts/lib/pregateAttestation.js`.+- **The tree binding.** The status description is+ `tree=<40-hex> stages=<list>`: the receipt's `git write-tree` hash of the+ exact working tree pregate validated, untracked and uncommitted files+ included. `pregate-attest.js` refuses unless `<commit>^{tree}` equals it —+ anything changed after pregate means a rerun — and the planner compares it+ with the head commit's tree on the PR. A SHA is never compared, for the same+ reason `scripts/verify-ci-status.js` compares trees: the content is what was+ tested. The commit must already be on the upstream remote (the one+ `branch.<name>.remote` names); GitHub only accepts a status on a commit it+ has, which is why attesting is a step after `git push`, not a pregate flag.+- **Who can post one.** A commit status on this repository can only be created+ by an actor with write access, and the planner honors only the newest+ successful `pregate` status whose `creator.login` is the repository owner.+ The `GITHUB_TOKEN` of a `pull_request` run from a fork is read-only and+ cannot create one; a Dependabot pull request is refused by author; a status+ by anyone else is ignored. The impact job holds `statuses: read` and nothing+ more (`release.yml` grants the same scope to the called workflow). CI is+ still the authority for every outsider.+- **When it applies.** Only a same-repository pull request into a non-`release`+ base that was not forced full. The planner verifies the merge-ref checkout's+ second parent is the event's head (so the tree compared is the tree under+ test) and reads `repos/{repo}/commits/{head}/statuses`. Any failure — API+ error, unreadable description, tree mismatch, wrong creator — leaves the+ plan exactly as computed and records the reason.+- **What CI still runs.** The impact job and its hidden-content scan, the+ Windows job, the Linux worker-containment job, the Node-minimum check and+ the `CI Gate` itself always run as planned. The server job stays when its+ boot smoke is selected but not attested, because the smoke runs on that job.+ An attested run reports `full: false`, so `Full CI Gate` is never published+ on the strength of a receipt. The planner reads the plan from the merge ref,+ so a test added on `main` after the local run can still be selected and+ then skipped under the attestation — the same class of gap the nightly+ full run on `main` exists to catch.+- **How to inspect it.** The impact job's summary prints a `Pregate+ attestation` line (`attested`, the head and tree, the stages, or the reason+ none applied) and `suite_reasons` names each skipped suite as attested.+ On the commit: `gh api repos/<owner>/<repo>/commits/<sha>/statuses` lists+ every `pregate` status with its creator, description and timestamp;+ `node scripts/pregate-attest.js --dry-run` shows what would be posted for+ the current receipt and HEAD without posting it.+### Vitest runner tuningOn GitHub Actions, `CI=true` caps the server Vitest runner at `maxWorkers: 4`@@ -554,12 +613,15 @@ The selected work is split across parallel jobs:them: `scripts/ci-gate-report.js` says *cancelled, not failed* and names thecancelled jobs when nothing actually failed — as far as the gate job itselfruns, which a run-wide cancel prevents. See "External cancellation and one- automatic retry" below.+ automatic retry" below. A job the planner skipped on a pregate attestation+ counts as passing here like any other skipped job; the impact summary and+ `suite_reasons` say which ones, and why (see "Pregate attestation").- **Full CI Gate** — published only when the plan chose the complete suite andfull Windows coverage, with the full browser profile executed in hosted CI.- Ordinary PR smoke runs cannot publish it.- It mirrors `CI Gate`'s result. This is the check the release workflow looks for;- see "Reusing the release PR's CI run" below.+ Ordinary PR smoke runs cannot publish it, and neither can a run that skipped+ any stage on a pregate attestation — the planner reports `full: false` for+ those. It mirrors `CI Gate`'s result. This is the check the release workflow+ looks for; see "Reusing the release PR's CI run" below.### Browser fidelity casesdiff --git a/docs/plans/README.md b/docs/plans/README.mdindex f744c05e4c..563b90d322 100644--- a/docs/plans/README.md+++ b/docs/plans/README.md@@ -9,6 +9,12 @@ implementation.- Each plan typically opens with a **Context** section (the problem and intendedoutcome), then the architecture, data model, and a verification section.+Index of plans other docs point at:++- [2026-10-18 — local-first merge gate](./2026-10-18-ci-local-first-merge-gate.md):+ the CI/test latency audit and the six changes behind the test memo, the+ resource suites in pregate, and the pregate attestation CI honors.+These are point-in-time design records, not living docs — they are not updatedto track implementation drift. For current behavior, see the code, `CLAUDE.md`,and the topic docs elsewhere under `docs/`.