Repository navigation
P0 coordination: enforce single-owner PRs and detect parallel edits before heavy CI #400
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.
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
Changes from all commits
15bf7c7
f396220
a7d6b99
8627432
9261342
99a89e2
f71dd08
975e27c
9b494db
0248a54
97f0403
b641530
c1afbec
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| ## Why this work is not duplicated | ||
| Current main SHA: `...` | ||
| Related issue / existing PRs reviewed: | ||
|
|
||
| ## REQUIRED agent ownership (replace CHANGE_ME before opening) | ||
| <!-- arsonmix-workstream: CHANGE_ME --> | ||
| <!-- arsonmix-issue: #397 --> | ||
|
|
||
| Allowed workstream: GUI / ENGINE / INTEGRATOR / FAT. | ||
| Only the owning lane edits each production file. See [coordination #397](https://github.com/masarray/arsonmix/issues/397) and [workstream rules](../docs/workstreams/MULTI_AGENT_COORDINATION.md). | ||
|
|
||
| ## Meaningful implementation and handoff | ||
| - Owned files changed: | ||
| - Existing implementation reused (PR/SHA): | ||
| - Native producer/consumer ABI change (if any): | ||
| - Exact-head targeted CI URL and demonstrated behavior: | ||
| - Real PCM/GUI/physical FAT proof or **PENDING**: | ||
| - Next blocked dependency + receiving workstream: | ||
|
|
||
| Do not create another GUI, PCM engine, duplicate routing graph, or second CI workflow. Avoid changing CMake/src/Main.cpp outside INTEGRATOR; test evidence is not an audio-LIVE claim. | ||
|
|
||
| If this older PR has been parked pending reconciliation, include: | ||
| <!-- arsonmix-coordination: parked --> | ||
| Remove the parked marker only after an owner-scoped diff and conflict audit. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -19,11 +19,14 @@ on: | |
| - 'tests/wire_graph_canonical_model.test.cjs' | ||
| - 'tests/wire_main_native_handoff_contract.test.cjs' | ||
| - 'tests/ci_workflow_efficiency_test.mjs' | ||
| - 'scripts/check_workstream_coordination.mjs' | ||
| - 'tests/workstream_coordination_contract.test.mjs' | ||
| - 'tests/approved_native_m2_contract.test.cjs' | ||
| - 'scripts/build_ui_css.py' | ||
| - '.github/workflows/ui-smoke.yml' | ||
| - '.github/workflows/pages-publish.yml' | ||
| pull_request: | ||
| types: [opened, reopened, synchronize, ready_for_review] | ||
| paths: | ||
| - 'web/**' | ||
| - 'integration/console-v6/**' | ||
|
|
@@ -37,6 +40,8 @@ on: | |
| - 'tests/native_ui_contract_test.mjs' | ||
| - 'tests/native_orbit_ui_smoke.py' | ||
| - 'tests/ci_workflow_efficiency_test.mjs' | ||
| - 'scripts/check_workstream_coordination.mjs' | ||
| - 'tests/workstream_coordination_contract.test.mjs' | ||
| - 'tests/approved_native_m2_contract.test.cjs' | ||
| - 'tests/wire_graph_canonical_model.test.cjs' | ||
| - 'tests/wire_main_native_handoff_contract.test.cjs' | ||
|
|
@@ -53,6 +58,7 @@ concurrency: | |
|
|
||
| permissions: | ||
| contents: read | ||
| pull-requests: read | ||
|
|
||
| jobs: | ||
| frontend: | ||
|
|
@@ -61,6 +67,11 @@ jobs: | |
| timeout-minutes: 20 | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - name: Cheap one-owner / overlapping-PR preflight (read-only) | ||
| if: ${{ github.event_name == 'pull_request' }} | ||
| env: | ||
| GH_TOKEN: ${{ github.token }} | ||
|
Comment on lines
+70
to
+73
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Both AGENTS.md reference: AGENTS.md:L15-L15 Useful? React with 👍 / 👎. |
||
| run: node scripts/check_workstream_coordination.mjs --pr ${{ github.event.pull_request.number }} | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.12" | ||
|
|
@@ -79,7 +90,7 @@ jobs: | |
| node --check web/plugin-ui.js | ||
| node --check web/mixer-io.js | ||
| node --check web/mixer-layout.js | ||
| node --test tests/gui_workflow_contract_test.mjs tests/plugin_ui_contract_test.mjs tests/ci_workflow_efficiency_test.mjs tests/fx_drag_reorder_contract_test.mjs tests/mixer_io_operator_contract_test.mjs tests/mixer_shell_contract_test.mjs tests/approved_native_m2_contract.test.cjs | ||
| node --test tests/workstream_coordination_contract.test.mjs tests/gui_workflow_contract_test.mjs tests/plugin_ui_contract_test.mjs tests/ci_workflow_efficiency_test.mjs tests/fx_drag_reorder_contract_test.mjs tests/mixer_io_operator_contract_test.mjs tests/mixer_shell_contract_test.mjs tests/approved_native_m2_contract.test.cjs | ||
| - name: Validate approved GUI checkpoint and single publisher | ||
| run: python tests/gui_baseline_lock_test.py | ||
| - name: CSS V28 zero-regression source-order recovery (every GUI CI run) | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| # ArSonMix — Parallel Agent Coordination (binding for new work) | ||
|
|
||
| **Control tower:** [issue #397](https://github.com/masarray/arsonmix/issues/397). | ||
| **Product authority:** [AGENTS.md](../../AGENTS.md) + ONLY the assembled [approved /preview/](https://masarray.github.io/arsonmix/preview/). Do not replace either with an agent-generated UI or JS audio engine. | ||
|
|
||
| ## Four workstreams, one file owner | ||
|
|
||
| | Lane | Only this lane may edit these production paths | What other lanes provide | | ||
| | --- | --- | --- | | ||
| | GUI | `site/**`, presentation in `web/**`, `scripts/build_pages.py`, CSS and hardware-button assets | Screenshots, interaction tests, exact immutable approved Pages artifact | | ||
| | ENGINE | `engine/**`, audio/DSP/driver `src/**` except native GUI seam, VST3 and callback | Native-produced ChannelId/EdgeId snapshots, PCM tests and performance evidence | | ||
| | INTEGRATOR | `src/Main.cpp`, `CMakeLists.txt`, `integration/**`, `web/approved-native*`, native GUI resource builder, workflow/coordination policy | Reconciles accepted GUI and ENGINE ABI; no second GUI/PCM; owns merged Windows assembly | | ||
| | FAT | Native Windows package/verification scripts, hardware and QA regression evidence | Independent end-to-end exact-SHA verdict; never rewrites DSP or GUI for PASS | | ||
|
|
||
| Unclassified docs and isolated tests can be authored by their domain owner. A change to a source file outside a lane **must be handed to the owning lane**. Example: ENGINE can propose a diff to `src/Main.cpp` but INTEGRATOR applies it with the accepted native ABI. FAT files cannot silently turn off safety checks. "Working on a PR" does not grant a file lock against GitHub account credentials: this is enforceable-by-CI collaboration policy, not a security boundary. | ||
|
|
||
| ## Before every coding session (GitHub is the live coordination bus) | ||
|
|
||
| 1. Fetch current `main` SHA, root `AGENTS.md`, issue #397, and the active PR list with changed filenames. Check whether another PR or `main` has already implemented your milestone. | ||
| 2. Read your own workstream and the accepted contract. If your desired file is owned by another lane, **write a targeted handoff**, not another implementation. | ||
| 3. Reconcile stale branch state against `main`, preserve unique tests only, and keep preview artwork byte-identical. Never blind-merge old #266/#270/#393/#395 branches. | ||
| 4. Put these metadata markers in each **new** PR body (replace OWNER and issue number): | ||
|
|
||
| ```text | ||
| <!-- arsonmix-workstream: GUI --> | ||
| <!-- arsonmix-issue: #397 --> | ||
| ``` | ||
|
|
||
| Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number when more specific than #397. A temporarily frozen legacy PR may carry `<!-- arsonmix-coordination: parked -->`; remove it only after a fresh ownership + conflict audit. | ||
|
|
||
| ## Low-cost CI guard (no extra workflow) | ||
|
|
||
| `scripts/check_workstream_coordination.mjs` is executed at the start of both **existing** Windows and Chromium workflows on PRs, using GitHub's read-only PR/files API. For PRs created **from #400 onward**, it fails on missing metadata, wrong-owner edits, and changed-file or same-runtime-domain overlap with another active PR that owns the same PCM, bridge or GUI path (even if the filenames differ). | ||
|
|
||
| A pre-policy **DRAFT** PR (up to #399) gets **nonblocking findings** to avoid abruptly halting the current ENGINE/FAT branches. Promotion to **ready_for_review** triggers both existing CI paths again and is STRICT, including owner metadata and active-file conflicts. Do not confuse the grandfathering with merge approval: #266 remains the ENGINE producer; stale or overlapping PRs are reconciled and reviewed, not blindly merged. Parked PRs do not claim a file. The current owner can continue when an older branch edits that owner's file unlawfully; the old branch is flagged for handoff instead. | ||
|
|
||
| This preflight is **fast and read-only**, runs before JUCE checkout and before browser dependencies, and adds no Windows work for GUI-only changes. If GitHub API cannot be checked, a new PR fails rather than receiving a fictional PASS. Use `node --test tests/workstream_coordination_contract.test.mjs` locally for pure offline regression. | ||
|
|
||
| ## Handoff format (comment on #397 plus relevant technical PR) | ||
|
|
||
| ```text | ||
| WORKSTREAM: GUI | ENGINE | INTEGRATOR | FAT | ||
| BASE main SHA: | ||
| PR / head SHA: | ||
| OWNED FILES CHANGED: | ||
| NATIVE ABI / fixture / ChannelId + EdgeId implications: | ||
| EXACT-HEAD PASS (URLs, not assumptions): | ||
| BLOCKER / owner needed: | ||
| NEXT SINGLE MEANINGFUL MILESTONE: | ||
| ``` | ||
|
|
||
| Do not create 10 micro-PRs or issue-only progress in place of code. The owning lane implements substantive code and targeted tests; one integrator joins exact checked SHA. GUI remains Pages-only visual authority; only ENGINE provides real PCM; FAT is the independent final judge. If the device is unavailable, mark physical FAT pending. Keep #15 crackling stop-ship. | ||
|
|
||
| ## Administrative limitation | ||
|
|
||
| GitHub may allow a maintainer to merge even with a failed check unless **required status checks** and appropriate branch protection/rulesets are configured. App connections cannot always administer these. Treat #397 as the human coordination gate, and enable branch protection for existing Windows/Chromium checks (or a dedicated required coordination check if introduced later) through repository Settings when available. This policy does not magically observe unpushed private ChatGPT threads. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For a new PR created from this template, replacing
CHANGE_MEwith the correct owner still leaves an actual parked marker in the body.metadata()matches that marker even though it follows instructional prose, so an otherwise valid PR fails withPR is PARKED; other PRs also exclude it from collision detection. Keep the example escaped or otherwise nonmatching, and require authors to insert the actual marker only when intentionally parking a PR.AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.