Skip to content

chore(stack): drain the integration overlays - #348

Merged
patroza merged 1 commit into
fork/devfrom
fork-dev/drain-overlays
Aug 6, 2026
Merged

chore(stack): drain the integration overlays#348
patroza merged 1 commit into
fork/devfrom
fork-dev/drain-overlays

Conversation

@omegent-app

@omegent-app omegent-app Bot commented Aug 6, 2026

Copy link
Copy Markdown

Closes the overlay era. fork/dev was cut from the composed fork/integration tip, so every
registered overlay's product content has been in fork/dev since the cutover.

Containment re-verified against the current tip

Overlay PR Commits present in fork/dev
fork/identity #250 17 / 17
t3-discord/f7d37879-desktop-deeplinks #254 8 / 8
fork/discord #174 9 / 12
fork/vscode #175 2 / 3

The four that are not present touch pnpm-lock.yaml only — checked by path, not by subject. They
are regeneration artifacts that compose discards by its own pnpm-lock.yaml -> theirs rule and
replaces with its own lockfile commit. No product content sits outside fork/dev.

Change

  • integrationOverlays emptied in .github/pr-stack.json.
  • The matching pull_request bases dropped from fork-ci.yml, which carried an explicit instruction
    to stay in sync with that list.

Overlay PRs #254, #174, #175 and #250 are closed alongside this. Leaving them open against
fork/changes would duplicate their commits the next time anything composes — the one ordering
hazard called out in #342.

Scope

Deliberately narrow. The overlay machinery itself — compose-integration,
rebase-integration-overlays, force-update-overlay-tip, client-overlay-ownership and the
surrounding docs — is left in place. Removing it touches ~20 files and is a separate decision; it
still passes its own tests with an empty manifest.

Validation

  • fork-stack, rebase-pr-stack, compose-integration-overlays, client-overlay-owner and
    rebase-integration-overlays suites: 69/69 pass against the empty manifest, so the tooling
    tolerates zero overlays rather than assuming at least one.
  • vp fmt --check clean.

Co-authored by @patroza

opened by Patrick Roza in chat thread Discord · Discord · T3

@omegent-app @patroza
chore(stack): drain the integration overlays
7b2a4f1 
fork/dev was cut from the composed fork/integration tip, so every registered
overlay's product content has been in fork/dev since the cutover. Verified
again against the current tip: identity 17/17 and desktop-deeplinks 8/8 commits
present, and the four that are not present (discord 3, vscode 1) touch
pnpm-lock.yaml only — regeneration artifacts that compose discards by its own
"pnpm-lock.yaml -> theirs" rule and replaces with its own lockfile commit.

Empty integrationOverlays and drop the matching pull_request bases from
fork-ci.yml, which carried an explicit instruction to stay in sync with it.
Overlay PRs #254, #174, #175 and #250 are closed alongside this; leaving them
open against fork/changes would duplicate their commits the next time anything
composes.

Scoped deliberately. The overlay machinery itself — compose-integration,
rebase-integration-overlays, force-update-overlay-tip, client-overlay-ownership
and the surrounding docs — is left in place and still passes its tests with an
empty manifest (69/69). Removing it is a larger change and a separate decision.

Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
This was referenced Aug 6, 2026
Closed
Closed
Closed
Closed
@patroza
patroza merged commit 6a982f7 into fork/dev Aug 6, 2026
5 checks passed
@omegent-app omegent-app Bot mentioned this pull request Aug 6, 2026
Merged
omegent-app Bot added a commit that referenced this pull request Aug 6, 2026
@patroza @github-actions @omegent-app
docs: record the stable fork/dev development and release branch (#342)
65c3850 
Records the `fork/dev` development and release model — **adopted and
live since 2026-08-06**. This
started as a proposal; the migration then ran ahead of it, so the
document is now the record rather
than the plan.

Documentation only. Every mechanism it describes is already merged and
running.

## The model

`fork/dev` is the default branch, the contributor target and the release
source. It is never rebased.
The provenance stack `main → fork/base → fork/tim → fork/candidates`
stays rebased and feeds
`fork/dev` through reviewed tree deltas, so contributor bases are never
invalidated by an upstream
update.

| In place | |
| --- | --- |
| `fork/dev` cut from green `fork/integration` `21badd04e`, trees proven
identical | tag `fork-dev/2026-08-06.1` |
| Default branch, ruleset, squash-only, required checks | live |
| CI for `fork/dev` PRs and merges | #343 |
| Deployment promoting exact green `fork/dev` SHAs | ops `deploy.env` |
| Validation and release split | #347, #349 |
| First provenance sync, upstream `2a04db134..a2ca89a` | #345, tag
`fork-dev/2026-08-06.2` |
| Upstream ancestry recorded so "behind" reads true | `3a7e7a458` |
| Overlays drained and deregistered | #348 |

## What this revision corrects

The document had drifted from what was actually built:

- **Release is two workflows, not one.** `fork-ci` decides whether a SHA
is valid; `fork-release`
acts on that verdict via `workflow_run`. A release action must never be
able to veto a validation
verdict — when mobile dispatch lived inside `fork-ci`, one failed EAS
call marked a valid SHA
  unapprovable and stranded the whole fleet.
- **Check selection is *not* path-inferred**, and the document
previously implied it should be. Every
PR runs all four required checks; only *release* scope is classified. A
path filter that errs
narrow silently skips a check on a protected branch, which is worse than
a slightly slower suite.
- **`fork/changes` and `fork/integration` are frozen**, not fallbacks.
- Ops parameterization and the `deploy.env` cutover are **done**, not
pending.
- Steps that were "do now" are recorded as done, with real SHAs, tags
and ruleset contents.

## What the cutover surfaced

Added as a section, because each cost a round trip and the old path hid
all of them:

- `fork/dev` had **no CI path at all** — no `push` trigger, not listed
as a `pull_request` base.
- **Mobile releases would have stopped silently**; nothing errors when a
gated job just never fires.
- Both mobile workflows **hardcoded `ref: fork/integration`** and
rejected every `fork/dev` SHA.
- A release failure could **strand the fleet**.
- **Every PR based on `fork/changes` was already broken** by earlier
rebases — GitHub reported them
as 60–100 commits and 629–741 files. Each was one commit of real work on
stale history, fixed by
  cherry-picking that commit rather than replaying the branch.

That last one is the clearest evidence for the whole premise: the old
model was silently corrupting
in-flight work, and nobody could see it.

## Deliberately not done

Clean downstream projection is deferred indefinitely and nothing depends
on it. Provenance sync stays
manual. The overlay machinery is still present and still passes its
tests with an empty manifest;
removing it touches ~20 files and is a separate decision.

## Still open

PRs #317, #226 and #185 conflict when cherry-picked onto `fork/dev`;
#237 and #238 live in an
external fork and need their author. `fork/changes` and
`fork/integration` can be deleted once those
are drained.

## Also: no guidance targets an overlay any more

The overlays were drained in #348, but the instructions an agent or
contributor actually reads before
opening a PR still sent them at `fork/discord`, `fork/vscode`,
`fork/identity`, the desktop
deep-links branch, or `fork/changes`. Left alone, the next client-owned
change would have been opened
against a **closed overlay on a frozen branch**.

- **`CLAUDE.md`** (`AGENTS.md` symlinks to it): branch from and target
`fork/dev` for every kind of
work; `main`, `fork/changes` and `fork/integration` named as bases never
to use; the
"register an `integrationOverlays` entry" instructions replaced with a
record that it is empty.
- **`apps/discord-bot/docs/agent-turn-rules.md`**: recovery branches
pointed at *"the correct base
  (`fork/discord` overlay / `fork/changes` / etc.)"* → `fork/dev`.
- **`fork-stack.md`, `stack-ship-path.md`, `client-overlays.md`**:
bannered as superseded rather than
rewritten — the provenance stack they document is still current and they
are the record of how the
fork worked before the cutover. The two lines that literally instructed
a base are corrected.

Verified by grep: nothing in the repository still directs a PR anywhere
but `fork/dev`.

## Validation


`vp fmt --check` clean; internal anchors checked. Documentation only —
no code, tooling or workflow
changes in this PR.

Co-authored by [@patroza](https://github.com/patroza)

opened by [Patrick Roza](https://discord.com/users/95218063095377920) in
chat thread **Discord** ·
[Discord](https://discord.com/channels/1083767712431480922/1534783738322485399/1534783738322485399)
· [T3](https://t3vm/?thread=584a9ad3-243e-4308-8a13-49acdd758b17)

---------

Co-authored-by: T3 Code PR Stack <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: omegent-app[bot] <306514130+omegent-app[bot]@users.noreply.github.com>
Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
@omegent-app omegent-app Bot mentioned this pull request Aug 6, 2026
Merged
patroza added a commit that referenced this pull request Aug 6, 2026
@omegent-app @patroza
ci(fork): run PR checks when a PR is retargeted or marked ready (#359)
ace285b 
Fixes the cause of [#357](#357)
sitting on four required checks
that could never report.

## What happened

`pull_request` defaults to the activity types `opened`, `synchronize`,
`reopened`. #357's timeline:

| Event | Activity type | Result |
| --- | --- | --- |
| force-pushed while base was `fork/discord` | `synchronize` |
**filtered** — #348 removed the overlay bases from this workflow's
`branches` list |
| base changed `fork/discord` → `fork/dev` | `edited` | **not** a
default type |
| marked ready for review | `ready_for_review` | **not** a default type
|

So the PR never emitted a watched event while sitting on a watched base.
Zero `fork-ci` runs existed
for its head SHA, the four required checks stayed `Expected — Waiting
for status to be reported`, and
auto-merge waited on something that had no way to arrive. Toggling
draft/ready and re-enabling
auto-merge could not help, because none of those are trigger types
either.

## Change

List the activity types explicitly and add both missing ones:

```yaml
types: [opened, synchronize, reopened, ready_for_review, edited]
```

`edited` also fires for **title and body edits**, which happen
constantly here and must not spend a
full CI run including a macOS runner. `github.event.changes.base` is
populated only when the base
actually changed, so each job skips an edit that did not move the base.

## Unblocking #357 itself

Closed and reopened it — `reopened` **is** a default type, so it fires
against the current base
without adding a commit to the branch. Checks are running there now.

## Scope

I checked every open PR on `fork/dev`: only #357 was affected. The
others were based on
`fork/changes`, which is still in the `branches` list, so their pushes
did produce runs. This was
specifically a PR that had been sitting on an overlay base when those
bases were removed — a
transitional hazard from the drain, but one worth closing since a
required check that can never
report is indistinguishable from a hung CI system.

Co-authored by [@patroza](https://github.com/patroza)

opened by [Patrick Roza](https://discord.com/users/95218063095377920) in
chat thread **Discord** ·
[Discord](https://discord.com/channels/1083767712431480922/1534783738322485399/1534783738322485399)
· [T3](https://t3vm/?thread=584a9ad3-243e-4308-8a13-49acdd758b17)

Co-authored-by: omegent-app[bot] <306514130+omegent-app[bot]@users.noreply.github.com>
Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
@omegent-app omegent-app Bot mentioned this pull request Aug 6, 2026
Merged
patroza added a commit that referenced this pull request Aug 6, 2026
@omegent-app @patroza
chore(stack): remove stack tooling, scope the draft lock, align docs (#…
707b68a 
…364)

Nothing drives this machinery any more. Overlays were drained and
deregistered, `fork/changes` and
`fork/integration` are frozen, and upstream is now merged **straight
into `fork/dev`** — a plain
`git merge`, because upstream is append-only and the previous sync
recorded its ancestry.

## Removed

| | |
| --- | --- |
| Scripts | `fork-stack.ts`, `rebase-pr-stack.ts`,
`compose-integration-overlays.ts`, `rebase-integration-overlays.ts`,
`client-overlay-owner.ts` + all 5 test files |
| Workflows | `compose-integration.yml`, `rebase-pr-stack.yml`,
`force-update-overlay-tip.yml` |
| Config | `.github/client-overlay-ownership.json` |
| `package.json` | `fork:stack`, `fork:stack:sync`,
`fork:overlay-owner`, `fork:rebase-overlays` |
| Docs | `stack-ship-path.md`, `client-overlays.md` |

## Kept, deliberately

**`classify-deployment-diff.sh` is not stack tooling.** It is the shared
definition of what a diff
means, run by *both* `fork-release` and the smart-host poller so the two
cannot disagree about what
ships. Its tests still pass.

**`managed-pr-draft-lock.yml` still guards #255, #1 and #27**, which
remain open drafts. Merging #255
would push fork CI plumbing into the upstream mirror — that lock matters
*more* now that nothing else
watches those branches. `pr-stack.json` survives purely as its
allowlist, trimmed to those three PRs
and annotated to say so.

## A latent bug found on the way

The draft lock read its allowlist from `?ref=fork/changes` — a **frozen
branch**. Any edit to the
manifest could never have taken effect, including the overlay
deregistration in #348. It now reads
`fork/dev`.

## Guidance rewritten, not just deleted

`AGENTS.md` referenced removed commands in a dozen places (`pnpm
fork:stack update --push`,
`node scripts/rebase-pr-stack.ts sync --push`, …). Deleting the scripts
without this would have sent
an agent to a script that no longer exists. `fork-stack.md`,
`stack-history-rewrite.md` and
`fork-base.md` are bannered or corrected rather than deleted — the
branches they describe still
exist even though the workflow around them does not.

## Draft lock: no longer runs on unrelated PRs

It triggered on **every** pull request, started a run, looked itself up
in an allowlist, exited, and
left a `Keep managed PR draft` check on PRs it had nothing to do with.

Now filtered to the bases the managed PRs actually target — `main`,
`fork/base`, `fork/tim`. Ordinary
work targets `fork/dev`, so it does not run there at all.

**Not folded into Fork CI**, which was the other option. Fork CI
deliberately does not watch `main`,
and **#255 targets `main`** — merging that pushes fork CI plumbing into
the upstream mirror, the
single worst outcome this guard prevents. Folding it in would have
quietly dropped the guard on the
one PR that most needs it.

## Docs aligned to what is actually running

- The handover doc's synchronization section described rebuilding the
provenance stack and importing
a `C1..C2` tree delta. Rewritten around the direct merge, keeping a
short *what this replaced* note
  and why that was never necessary for upstream in the first place.
- Core invariants and operational rules no longer instruct importing a
tree delta or recording
  ancestry with `merge -s ours`.
- **`fork-stack.md`**: 714 lines describing the removed workflow → a
short topology doc. What each
branch is, that the provenance branches are no longer rebuilt, that
their PRs stay draft.
- **`stack-history-rewrite.md`**: deleted with its inbound links. It
documents rewriting stack
  history, which no longer happens.

`docs/` is now `fork-base.md`, `fork-stack.md`, `README.md`,
`sidebar-v2.md`,
`stable-dev-release-branch-handover.md`.

Verified: no reference anywhere to removed tooling or deleted docs, and
no broken internal links in
the handover doc.

## Validation


- Full recursive typecheck clean across 17 packages.
- **2248 tests pass.** The one failure (`CodexTextGeneration` structured
output) reproduces on
  `fork/dev` unmerged and predates this change.
- `classify-deployment-diff.test.sh` passes.
- The draft lock's exact `jq` query verified against the trimmed
manifest: matches #27, rejects an
  unmanaged number.

## Not done

`docs/fork-stack.md` is kept (bannered). It has ~10 inbound links from
`AGENTS.md` and documents the
provenance branches, which still exist. Removing it is a further docs
pass, not part of deleting the
tooling.

Co-authored by [@patroza](https://github.com/patroza)

opened by [Patrick Roza](https://discord.com/users/95218063095377920) in
chat thread **Discord** ·
[Discord](https://discord.com/channels/1083767712431480922/1534783738322485399/1534783738322485399)
· [T3](https://t3vm/?thread=584a9ad3-243e-4308-8a13-49acdd758b17)

---------

Co-authored-by: omegent-app[bot] <306514130+omegent-app[bot]@users.noreply.github.com>
Co-authored-by: Patrick Roza <42661+patroza@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@patroza