From b26a004113895242ba8a557d79bbd09bb69b297e Mon Sep 17 00:00:00 2001 From: Ame <123734885+luokerenx4@users.noreply.github.com> Date: Sun, 12 Jul 2026 00:02:32 +0800 Subject: [PATCH 1/2] docs: pipeline serial dev CI feedback --- AGENTS.md | 13 ++++++++---- docs/development-workflow.md | 41 ++++++++++++++++++++++++++++-------- 2 files changed, 41 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df74dda3c..9f3a7d117 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,14 +70,19 @@ 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. 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 diff --git a/docs/development-workflow.md b/docs/development-workflow.md index 8fb9a0047..82b85e4a1 100644 --- a/docs/development-workflow.md +++ b/docs/development-workflow.md @@ -54,11 +54,16 @@ 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 is the integration carrier and audit record, 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 @@ -89,6 +94,9 @@ git add git commit -m "" 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 --merge --delete-branch ``` The PR body should contain: @@ -110,14 +118,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. @@ -127,7 +143,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 @@ -250,7 +268,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 | From fd433bff25d33f588ad0425f6742072cb17b7863 Mon Sep 17 00:00:00 2001 From: Ame <123734885+luokerenx4@users.noreply.github.com> Date: Sun, 12 Jul 2026 00:03:01 +0800 Subject: [PATCH 2/2] docs: clarify PR roles by delivery mode --- AGENTS.md | 15 +++++++++------ docs/development-workflow.md | 9 ++++++--- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9f3a7d117..f90d2303f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,12 +76,15 @@ Choose delivery authority before implementation: | 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. 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 +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)). diff --git a/docs/development-workflow.md b/docs/development-workflow.md index 82b85e4a1..28f44d18a 100644 --- a/docs/development-workflow.md +++ b/docs/development-workflow.md @@ -61,9 +61,10 @@ steering concrete work. 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 and audit record, 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. +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 @@ -80,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