Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
24 changes: 24 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
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.
Comment on lines +22 to +24

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the active parked marker from the default PR template

For a new PR created from this template, replacing CHANGE_ME with 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 with PR 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 👍 / 👎.

8 changes: 8 additions & 0 deletions .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ on:
# Native bridge changes still require Windows; pure visual GUI follows Pages only.
# A full executable/package is still produced on native main and explicit FAT.
pull_request:
types: [opened, reopened, synchronize, ready_for_review]
paths:
- 'CMakeLists.txt'
- 'integration/console-v6/**'
Expand Down Expand Up @@ -59,13 +60,19 @@ concurrency:

permissions:
contents: read
pull-requests: read

jobs:
windows-build:
runs-on: windows-2022
timeout-minutes: 50
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 }}
run: node scripts/check_workstream_coordination.mjs --pr ${{ github.event.pull_request.number }}
- name: Cheap canonical Console v6 puzzle socket gate (no JUCE)
run: node scripts/check_console_puzzle.mjs
- name: Stop incomplete integrated product promotion before JUCE checkout
Expand Down Expand Up @@ -100,6 +107,7 @@ jobs:
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}
$contracts = @(
'tests/workstream_coordination_contract.test.mjs'
'tests/gui_workflow_contract_test.mjs'
'tests/approved_native_m2_contract.test.cjs'
'tests/native_ui_contract_test.mjs'
Expand Down
13 changes: 12 additions & 1 deletion .github/workflows/ui-smoke.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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/**'
Expand All @@ -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'
Expand All @@ -53,6 +58,7 @@ concurrency:

permissions:
contents: read
pull-requests: read

jobs:
frontend:
Expand All @@ -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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Re-run the coordination check when PR metadata changes

Both ui-smoke.yml and p1-windows.yml retain default pull_request activity types, which GitHub documents as only opened, synchronize, and reopened. Consequently, correcting missing ownership metadata or removing a parked marker does not refresh a failed preflight; conversely, parking an already-green PR leaves its successful check unchanged. Since this newly added gate depends on mutable PR-body metadata, subscribe both existing workflows to edited as well, or provide an equivalent automatic revalidation path.

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"
Expand All @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,17 @@

**ONLY approved/public/product GUI: https://masarray.github.io/arsonmix/preview/**. There must be ONE public preview, ONE actual rendered GUI, and ONE native Windows GUI. **/preview-v2/ is rejected**: do not display, promote, publish or base native design on it as a separate UI. Do not substitute another console from `web/index.html`, `web/mixer-layout.js`, `web/console-native.html`, PR #278 or old M3/V48 mock. **The JUCE ENGINE must stitch into the EXACT approved /preview/ GUI**, never redesign it.

## Multi-agent GitHub coordination — REQUIRED (issue #397)

Before touching ArSonMix code, read [workstream ownership and collaboration contract](docs/workstreams/MULTI_AGENT_COORDINATION.md) and [coordination control tower #397](https://github.com/masarray/arsonmix/issues/397). GitHub main, active PRs, changed-file overlap and accepted native ABI are the shared state; independent ChatGPT threads cannot see each other's private unpushed work.

- **GUI** owns `site/**` and browser presentation. ONLY the assembled `/preview/`, no alternative renderer.
- **ENGINE** owns `engine/**` and realtime DSP/PCM/device/VST3 sources; **#266** remains sole callback producer.
- **INTEGRATOR** alone owns `src/Main.cpp`, `CMakeLists.txt`, `integration/**` and `web/approved-native*` and assembles one Windows application.
- **FAT** owns native Windows evidence, packaging and independent QA; FAT must not edit production DSP or GUI to claim PASS.

New PRs require the owner and linked issue metadata from `.github/PULL_REQUEST_TEMPLATE.md`. Existing Windows and Chromium workflows run the cheap, read-only source-owner/collision preflight; no extra workflow. Cross-owner changes must be handed off to the owner through issue #397, **not** implemented in parallel. Mark superseded older PRs `<!-- arsonmix-coordination: parked -->` while extracting unique verified changes. Pre-policy PRs #399 and earlier receive nonblocking findings while DRAFT; when marked ready_for_review they must meet the SAME strict gate and re-run CI. This is not permission to merge conflicting code. One exact-SHA integrator gates a Windows EXE on real native PCM + visual parity + FAT; missing hardware evidence is PENDING.

## Verified current published GUI implementation
`site/preview/index.html` was merely a wrapper/iframe pointing at a generated `/preview-buttons/index.html`. `scripts/build_pages.py` generates that **approved PNG hardware-button variant** using current `site/preview-v2/index.html` as an INTERNAL HTML/WIRE/FX/fader source, with specifically `site/preview-buttons/assets/mixer-control-keys.css`, `mixer-control-keys.js` and `mute-solo-pfl-56x37.png` as approved button source. **The assembled result behind /preview/ is the visual authority, not /preview-v2/ in isolation.** There must be exactly ONE deterministic assembled output and no independent published variant. Internal source files may survive only as build inputs until safely consolidated; they are NOT alternate product GUIs. **Current approved visual including PNG keys must never be silently replaced by the base variant.**

Expand Down
56 changes: 56 additions & 0 deletions docs/workstreams/MULTI_AGENT_COORDINATION.md
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.
Loading
Loading