Skip to content

docs: pipeline serial dev CI feedback #539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
luokerenx4 merged 2 commits into from
Jul 11, 2026
+47 −13
Merged

docs: pipeline serial dev CI feedback #539

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b26a004
docs: pipeline serial dev CI feedback
luokerenx4 Jul 11, 2026
fd433bf
docs: clarify PR roles by delivery mode
luokerenx4 Jul 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,14 +70,22 @@ for current ownership and entry points.

Choose delivery authority before implementation:

| Mode | Trigger | After a green PR to `dev` |
| Mode | Trigger | Delivery to `dev` |
|---|---|---|
| Serial / interactive | Default: the user is actively requesting and steering concrete work | Merge it, delete the feature branch, and return to updated `dev` unless the user says to pause |
| Serial / interactive | Default: the user is actively requesting and steering concrete work | After proportional local verification, open and merge the PR without waiting for pending remote CI; delete the feature branch and return to updated `dev` unless the user says to pause |
| Parallel / contribution | Explicit `/goal` or direct request to autonomously find and contribute improvements | Leave each PR open for later review, return to `dev`, and continue from a fresh branch |

A later interactive message does not retroactively authorize merging a parallel
PR queue. Detailed branch, PR, promotion, hotfix, and external-contribution
procedures live in [[docs/development-workflow.md]]
PR queue. Parallel work is already non-blocking because opening a PR does not
pause the next contribution. In serial work the PR exists to durably integrate
each completed increment into `dev`, so pending CI must not turn it into a
synchronous lock. Before publishing the next serial increment, inspect the
previous increment's PR checks and post-merge `dev` run. A known failure blocks
further stacking until repaired; a still-pending run does not by itself block
serial work. `master` promotions, releases, explicit review pauses, and
untrusted contributions keep their full synchronous gates. Detailed branch,
PR, promotion, hotfix, and external-contribution procedures live in
[[docs/development-workflow.md]]
([Development workflow](docs/development-workflow.md)).

## Verification
Expand Down
44 changes: 35 additions & 9 deletions docs/development-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,17 @@ steering concrete work.
1. Branch from current `dev`.
2. Explain material design choices while working.
3. Implement and run proportional verification.
4. Open a PR to `dev` and monitor the latest-head checks.
5. Unless the user requests a review pause, merge when green.
4. Before publishing the next increment, inspect the previous serial PR checks
and its post-merge `dev` run. Repair a completed failure before stacking more
work; record a still-pending run without waiting on it.
5. Open a PR to `dev`, confirm the intended base and head, and merge immediately
unless the user requests a review pause or earlier CI has a known failure.
6. Delete the merged feature branch and return to updated `dev`.

The PR is the integration carrier, not an automatic approval pause.
The PR durably integrates the completed increment into `dev` and records its
diff; it is not a synchronous CI or approval pause. Remote CI is
one-increment-delayed feedback in this mode: it continues after merge and must
be checked before the next serial publication.

### Parallel / contribution

Expand All @@ -75,6 +81,8 @@ For each coherent contribution:

The open PR queue becomes the later acceptance surface. A subsequent
interactive request does not retroactively authorize merging that queue.
Because these PRs are not merged during the contribution loop, their pending CI
never blocks starting the next independent contribution.

## Routine PR Flow

Expand All @@ -89,6 +97,9 @@ git add <intentional-files>
git commit -m "<terse outcome>"
git push -u origin HEAD
gh pr create --base dev --head "$(git branch --show-current)"

# Serial mode: after confirming the PR base/head, do not wait on pending CI.
gh pr merge <number> --merge --delete-branch
```

The PR body should contain:
Expand All @@ -110,14 +121,22 @@ the issue/PR that shaped the work.

## CI Feedback Lanes

CI distinguishes pre-merge confidence from post-merge integration so routine
agent iterations do not wait for the same full matrix twice:
CI provides both change-level confidence and post-merge integration feedback.
Its execution stays the same, but its blocking authority depends on the
delivery lane:

- Every PR to `dev` or `master` runs the Ubuntu build and test gate.
- PRs whose complete diff is limited to `ui/`, `docs/`, or root documentation
skip the macOS/Windows runtime matrix. Any other path keeps the full matrix.
- Superseded runs for the same PR are cancelled. Only the latest head is a
merge candidate.
- Superseded runs for the same PR are cancelled. Only the latest-head result is
actionable evidence.
- In serial mode, a `dev` PR may merge after proportional local verification
while its remote checks are pending. Before the next serial PR is published,
inspect both that PR's checks and the resulting `dev` push run. A completed
failure blocks further stacking until it is understood and repaired; pending
status alone does not block progress.
- Parallel/contribution PRs remain open for later acceptance. Their CI result
informs review but does not grant merge authority.
- A push to `dev` runs the focused Ubuntu Guardian/full-stack smoke instead of
repeating the PR's complete build, test, and cross-platform jobs.
- A push to `master` always runs the complete matrix.
Expand All @@ -127,7 +146,9 @@ agent iterations do not wait for the same full matrix twice:

Keep the lightweight-path allowlist narrow. Changes to dependencies, runtime,
Guardian, Electron, packaging, scripts, workflows, or any unclassified path
must continue through Windows and macOS before merge.
must still produce Windows and macOS evidence. In serial `dev` work that
evidence may arrive after merge, but a known failure stops the next increment;
it must be green before promotion to `master` or release.

## Merge and Cleanup

Expand Down Expand Up @@ -250,7 +271,12 @@ Keep `AGENTS.md` and `CONTRIBUTING.md` consistent with this guide and with

## Risk Gates

| Boundary | Gate before merge/promotion |
For a serial PR to `dev`, satisfy the locally runnable, surface-specific gate
before merging and report any platform-only residual risk. Remote platform
evidence may trail that merge under the feedback rule above. Before promotion
to `master` or release, every applicable gate must be complete and green.

| Boundary | Required evidence |
|---|---|
| Entry path, startup, onboarding, auth | Isolated first-run verification; keep a recovery/kill path for broad behavioral changes |
| Trading, broker writes, UTA permissions | Relevant demo/paper scenarios from `docs/uta-live-testing.md`; leave accounts flat |
Expand Down
Loading