From 15bf7c756a094a804aaea991151e8f7f3bc867e0 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:57:18 +0700 Subject: [PATCH 01/13] feat(coord): add cheap read-only PR owner/collision preflight for existing CI lanes --- scripts/check_workstream_coordination.mjs | 173 ++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 scripts/check_workstream_coordination.mjs diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs new file mode 100644 index 000000000..bed308c7d --- /dev/null +++ b/scripts/check_workstream_coordination.mjs @@ -0,0 +1,173 @@ +#!/usr/bin/env node +// SPDX-License-Identifier: AGPL-3.0-only +// One-owner PR preflight. Runs in EXISTING GUI/Windows workflows only. +// Cheap GitHub REST reads; NEVER changes a repo, builds audio or blocks push/main. +// New PRs fail closed on unowned production paths or active same-owner collisions. +import { pathToFileURL } from 'node:url'; + +export const POLICY_EPOCH_PR = 395; // Earlier PRs are reported, not retroactively failed. +export const WORKSTREAMS = Object.freeze(['GUI', 'ENGINE', 'INTEGRATOR', 'FAT']); + +export function ownerOf(path) { + if (path === 'AGENTS.md' || + path === '.github/PULL_REQUEST_TEMPLATE.md' || + path.startsWith('.github/workflows/') || + path === 'docs/workstreams/MULTI_AGENT_COORDINATION.md' || + path === 'scripts/check_workstream_coordination.mjs' || + path === 'tests/workstream_coordination_contract.test.mjs') + return 'INTEGRATOR'; + if (path === 'CMakeLists.txt' || path === 'src/Main.cpp' || + path.startsWith('integration/') || + /^src\/(ApprovedConsole|ApprovedNativeGui|ConsoleNativeTransport)/.test(path) || + /^web\/approved-native/.test(path) || + path === 'web/bridge.js' || path === 'web/monitor.js' || + path === 'scripts/build_approved_native_gui.py') + return 'INTEGRATOR'; + if (/^(scripts\/(package_native_windows|verify_native_windows_artifact)\.ps1)$/.test(path) || + /^tests\/(hardware_fat|native_artifact|fat_|windows_fat)/.test(path)) + return 'FAT'; + if (path.startsWith('site/') || path.startsWith('web/') || + path === 'AR-MIX-Live-FX-Host-Standalone-v0.3.html' || + path === 'scripts/build_pages.py' || + path === 'scripts/build_ui_css.py') + return 'GUI'; + if (path.startsWith('engine/') || path.startsWith('src/') || + path.startsWith('config/factoryfx-') || + path === 'scripts/factoryfx_release_bundle.py') + return 'ENGINE'; + return null; // docs / tests / independent CI fixtures are shared, read-only contracts. +} +export function metadata(body = '', headRef = '') { + const owner = body.match(//i)?.[1]?.toUpperCase() || null; + const issue = Number(body.match(//i)?.[1] || 0); + const parked = //i.test(body); + let inferred = owner; + if (!inferred && /^gui\//.test(headRef)) inferred = 'GUI'; + if (!inferred && /^(engine\/|milestone\/|fix\/p0-wasapi|feat\/factoryfx)/.test(headRef)) inferred = 'ENGINE'; + if (!inferred && /^(integration\/|coord\/)/.test(headRef)) inferred = 'INTEGRATOR'; + if (!inferred && /^work\/integration-fat/.test(headRef)) inferred = 'FAT'; + return {owner, inferred, issue, parked}; +} +export function audit({pr, files, others = [], filesByPR = {}}) { + const current = metadata(pr.body || '', pr.head?.ref || pr.headRef || ''); + const legacy = pr.number <= POLICY_EPOCH_PR; + const errors = [], warnings = []; + const changed = new Set(files); + const owners = new Set([...changed].map(ownerOf).filter(Boolean)); + if (!current.owner) errors.push('Declare in PR body'); + if (!current.issue) errors.push('Declare (or linked workstream issue) in PR body'); + if (current.parked) errors.push('PR is PARKED; remove parked marker only after owner reconciliation'); + if (current.owner) { + for (const file of changed) { + const owner = ownerOf(file); + if (owner && owner !== current.owner) + errors.push('CROSS-OWNER ' + file + ' belongs to ' + owner + + ', PR declares ' + current.owner + '. Request a handoff, do not edit the file.'); + } + } + for (const other of others) { + if (other.number === pr.number || other.state === 'closed') continue; + const peer = metadata(other.body || '', other.head?.ref || other.headRef || ''); + if (peer.parked) continue; + const shared = [...changed].filter(f => + (filesByPR[other.number] || []).includes(f)); + if (!shared.length) continue; + // The sole authorized owner must be free to progress. Legacy branches + // that edited somebody else's files are reported, not allowed to block. + const activeShared = shared.filter(f => { + const owner = ownerOf(f); + return owner && owner === current.owner && owner === peer.inferred; + }); + if (activeShared.length) { + errors.push('ACTIVE COLLISION with PR #' + other.number + ' (' + + (peer.inferred || 'UNKNOWN') + '): ' + activeShared.slice(0, 8).join(', ') + + (activeShared.length > 8 ? ' + ' + (activeShared.length - 8) + ' more' : '') + + '. Consolidate into ONE owner branch or park the superseded PR.'); + } else { + warnings.push('PR #' + other.number + ' also edits ' + shared.length + + ' path(s) outside its declared file owner; do not merge it raw.'); + } + } + if (legacy && errors.length) { + warnings.push('LEGACY migration (PR #' + pr.number + ' <= #' + + POLICY_EPOCH_PR + '): ' + errors.length + + ' ownership/collision finding(s), nonblocking until owner reconciliation'); + warnings.push(...errors); + } + return {ok: legacy || errors.length === 0, legacy, lane: current.owner || current.inferred, + owners:[...owners].sort(), errors:legacy?[]:errors, warnings, + changedFiles:changed.size, activeCollisions:errors.filter(x=>x.startsWith('ACTIVE COLLISION')).length}; +} + +async function apiJson(url, token) { + const response = await fetch(url, { + headers: { + 'Accept':'application/vnd.github+json', + 'Authorization':'Bearer ' + token, + 'X-GitHub-Api-Version':'2022-11-28', + 'User-Agent':'ArSonMix-workstream-preflight' + },signal:AbortSignal.timeout(15000) + }); + if (!response.ok) throw Error('GitHub REST ' + response.status + ' for ' + + new URL(url).pathname); + return response.json(); +} +async function allPages(base, token, limit = 10) { + const rows=[]; + for (let page=1;page<=limit;page++) { + const separator=base.includes('?')?'&':'?'; + const items=await apiJson(base+separator+'per_page=100&page='+page,token); + if (!Array.isArray(items)) throw Error('GitHub API returned non-array'); + rows.push(...items); + if(items.length<100) return rows; + } + throw Error('GitHub API pagination exceeded bounded limit: '+base); +} +export async function auditGitHub({repo,number,token}) { + if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(repo)) + throw Error('Invalid repository selector'); + if (!Number.isSafeInteger(number) || number<1 || !token) + throw Error('A valid PR number and a GitHub read token are mandatory'); + const prefix='https://api.github.com/repos/'+repo; + const [pr, others]=await Promise.all([ + apiJson(prefix+'/pulls/'+number,token), + allPages(prefix+'/pulls?state=open',token,4) + ]); + const filesByPR={}; + const scoped=others.filter(p=>p.number!==number && + !metadata(p.body||'',p.head?.ref||'').parked); + const files=await allPages(prefix+'/pulls/'+number+'/files',token,10); + // Bounded concurrency prevents API spikes on frequent PR pushes. + for (let i=0;i{ + filesByPR[item.number]=(await allPages(prefix+'/pulls/'+item.number+'/files',token,10)) + .map(f=>f.filename); + })); + } + return audit({pr,files:files.map(f=>f.filename),others,filesByPR}); +} +async function main() { + const args=process.argv.slice(2); + if(args.includes('--help')) { + console.log('Usage: node scripts/check_workstream_coordination.mjs --pr NUMBER'); + return; + } + const index=args.indexOf('--pr'); + const number=Number(index>=0?args[index+1]:0); + const result=await auditGitHub({ + repo:process.env.GITHUB_REPOSITORY || '', + number,token:process.env.GH_TOKEN || '' + }); + console.log('ArSonMix coordination: lane='+(result.lane||'UNDECLARED')+ + ' files='+result.changedFiles+' legacy='+result.legacy+ + ' authorized='+result.ok+' collision(s)='+result.activeCollisions); + for(const w of result.warnings)console.warn('::warning::'+w); + for(const e of result.errors)console.error('::error::'+e); + if(!result.ok)process.exitCode=1; +} +if(process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) { + main().catch(e=>{ + console.error('::error::Coordination API unavailable: '+e.message); + process.exitCode=1; // No invisible PASS if the new PR cannot be checked. + }); +} From f396220d5f98d152315364a8f67ab23b74b701aa Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:58:07 +0700 Subject: [PATCH 02/13] test(coord): enforce one-owner paths, PR conflict quarantine and legacy migration --- .../workstream_coordination_contract.test.mjs | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 tests/workstream_coordination_contract.test.mjs diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs new file mode 100644 index 000000000..38400d08b --- /dev/null +++ b/tests/workstream_coordination_contract.test.mjs @@ -0,0 +1,117 @@ +// SPDX-License-Identifier: AGPL-3.0-only +import test from 'node:test'; +import assert from 'node:assert/strict'; +import {readFileSync} from 'node:fs'; +import {POLICY_EPOCH_PR, ownerOf, metadata, audit} from '../scripts/check_workstream_coordination.mjs'; + +const body=(lane,issue=397,parked=false)=> + '\n'+ + ''+ + (parked?'\n':''); +const pr=(number,lane,branch,parked=false)=>({ + number,state:'open',head:{ref:branch},body:body(lane,397,parked) +}); +const check=(current,files,others=[],filesByPR={})=> + audit({pr:current,files,others,filesByPR}); + +test('only one approved GUI has GUI ownership; no accidental native source authority',()=>{ + for(const path of [ + 'site/preview/index.html', 'site/preview-v2/index.html', + 'site/preview/assets/mute-solo-pfl-56x37.png', + 'web/mixer-layout.js','web/styles.css','scripts/build_pages.py' + ]) assert.equal(ownerOf(path),'GUI',path); + for(const path of [ + 'engine/core/DynamicPreparedMixerBlock.h','src/LiveAudioEngine.h', + 'src/LiveDryRoutingLab.h','src/ConsoleLiveBridgeV6.h', + 'src/ApprovedNativeV8Projection.h' + ]) assert.equal(ownerOf(path),'ENGINE',path); + for(const path of [ + 'src/Main.cpp','CMakeLists.txt','web/approved-native-bridge.js', + 'scripts/build_approved_native_gui.py','.github/workflows/ui-smoke.yml', + 'AGENTS.md','integration/console-v6/contract.json' + ]) assert.equal(ownerOf(path),'INTEGRATOR',path); + for(const path of ['scripts/package_native_windows.ps1', + 'scripts/verify_native_windows_artifact.ps1']) + assert.equal(ownerOf(path),'FAT',path); + assert.equal(ownerOf('README.md'),null); +}); + +test('new GUI PR may edit approved source but cannot change native CMake or PCM',()=>{ + assert.equal(check(pr(401,'GUI','gui/fader'), + ['site/preview/index.html','site/preview/assets/meter.css']).ok,true); + const crossed=check(pr(401,'GUI','gui/fader'), + ['site/preview/index.html','CMakeLists.txt','src/LiveAudioEngine.h']); + assert.equal(crossed.ok,false); + assert.match(crossed.errors.join(' '),/CROSS-OWNER CMakeLists\.txt/); + assert.match(crossed.errors.join(' '),/CROSS-OWNER src\/LiveAudioEngine\.h/); +}); +test('new ENGINE PR cannot quietly replace JUCE native GUI bridge',()=>{ + const bad=check(pr(402,'ENGINE','engine/route'), + ['engine/core/DirectedGraph.h','src/Main.cpp','web/approved-native-bridge.js']); + assert.equal(bad.ok,false); + assert.match(bad.errors.join(' '),/src\/Main.cpp/); + assert.match(bad.errors.join(' '),/web\/approved-native-bridge\.js/); +}); +test('FAT owns independent packaging tests, not production audio source',()=>{ + const good=check(pr(403,'FAT','fat/hardware'),[ + 'scripts/package_native_windows.ps1','docs/FIRST_SOUND_FAT_QUICKSTART_20261101.md' + ]); + assert.equal(good.ok,true); + assert.equal(check(pr(403,'FAT','fat/hardware'),['src/LiveAudioEngine.h']).ok,false); +}); +test('new PR must explicitly declare role and linked issue',()=>{ + const candidate={number:405,head:{ref:'gui/new'},body:''}; + const result=check(candidate,['site/preview/index.html']); + assert.equal(result.ok,false); + assert.match(result.errors.join('\n'),/arsonmix-workstream/); + assert.match(result.errors.join('\n'),/arsonmix-issue/); + assert.equal(metadata(body('INTEGRATOR')).owner,'INTEGRATOR'); +}); +test('same-owned-file overlapping LIVE PR is rejected, never two owners',()=>{ + const candidate=pr(405,'GUI','gui/fader'); + const peer=pr(399,'GUI','gui/approved'); + const result=check(candidate,['site/preview/index.html'],[peer], + {'399':['site/preview/index.html','site/preview/assets/fx-rack.css']}); + assert.equal(result.ok,false); + assert.match(result.errors.join('\n'),/ACTIVE COLLISION with PR #399/); +}); +test('parked draft becomes nonblocking; unique changes can be reconciled later',()=>{ + const candidate=pr(405,'GUI','gui/fader'); + const peer=pr(393,'GUI','gui/one-approved-preview',true); + assert.equal(check(candidate,['site/preview/index.html'],[peer], + {'393':['site/preview/index.html']}).ok,true); +}); +test('legacy cross-owner edits are warned but cannot block rightful integrator',()=>{ + const candidate=pr(405,'INTEGRATOR','integration/native'); + const stale=pr(266,'ENGINE','milestone/m5-universal-channelid',false); + const result=check(candidate,['src/Main.cpp'],[stale], + {'266':['src/Main.cpp','src/LiveAudioEngine.h']}); + assert.equal(result.ok,true); + assert.match(result.warnings.join(' '),/outside its declared file owner/); +}); +test('active same-owner native bridge collisions ARE blockers',()=>{ + const candidate=pr(405,'INTEGRATOR','integration/native'); + const current=pr(409,'INTEGRATOR','integration/bridge'); + const result=check(candidate,['src/Main.cpp'],[current],{'409':['src/Main.cpp']}); + assert.equal(result.ok,false); + assert.equal(result.activeCollisions,1); +}); +test('pre-policy PRs remain report-only during migration, not retroactively blocked',()=>{ + const old={number:POLICY_EPOCH_PR,head:{ref:'integration/old'},body:''}; + const result=check(old,['src/LiveAudioEngine.h']); + assert.equal(result.ok,true); + assert.equal(result.legacy,true); + assert.match(result.warnings.join(' '),/LEGACY migration/); +}); +test('coordinator uses existing native + Chromium CI, not a fifth workflow',()=>{ + const native=readFileSync('.github/workflows/p1-windows.yml','utf8'); + const ui=readFileSync('.github/workflows/ui-smoke.yml','utf8'); + for(const text of [native,ui]){ + assert.match(text,/scripts\/check_workstream_coordination\.mjs --pr/); + assert.match(text,/pull-requests: read/); + assert.match(text,/GH_TOKEN: \$\{\{ github\.token \}\}/); + } + const guide=readFileSync('AGENTS.md','utf8'); + assert.match(guide,/MULTI_AGENT_COORDINATION\.md/); + assert.match(guide,/#397/); +}); From a7d6b99c79d347923596d2e465f6f5fb8267a109 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:58:57 +0700 Subject: [PATCH 03/13] docs(coord): one-owner GitHub control tower and fail-closed parallel agent handoff protocol --- docs/workstreams/MULTI_AGENT_COORDINATION.md | 56 ++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/workstreams/MULTI_AGENT_COORDINATION.md diff --git a/docs/workstreams/MULTI_AGENT_COORDINATION.md b/docs/workstreams/MULTI_AGENT_COORDINATION.md new file mode 100644 index 000000000..1da904967 --- /dev/null +++ b/docs/workstreams/MULTI_AGENT_COORDINATION.md @@ -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 + + +\`\`\` + +Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number when more specific than #397. A temporarily frozen legacy PR may carry \`\`; 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 **after #395**, it fails on missing metadata, wrong-owner edits, and changed-file overlap with another active PR that truly owns the same path. + +A pre-policy PR (up to #395) gets **nonblocking findings** to avoid abruptly halting the current ENGINE/FAT branches. 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. From 8627432b78c2844b07409e3d37630e7d74f6426a Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:59:19 +0700 Subject: [PATCH 04/13] docs(coord): render code spans and handoff examples correctly --- docs/workstreams/MULTI_AGENT_COORDINATION.md | 26 ++++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/workstreams/MULTI_AGENT_COORDINATION.md b/docs/workstreams/MULTI_AGENT_COORDINATION.md index 1da904967..7ae1e3238 100644 --- a/docs/workstreams/MULTI_AGENT_COORDINATION.md +++ b/docs/workstreams/MULTI_AGENT_COORDINATION.md @@ -7,38 +7,38 @@ | 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 | +| 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. +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. +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. +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 +```text -\`\`\` +``` -Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number when more specific than #397. A temporarily frozen legacy PR may carry \`\`; remove it only after a fresh ownership + conflict audit. +Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number when more specific than #397. A temporarily frozen legacy PR may carry ``; 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 **after #395**, it fails on missing metadata, wrong-owner edits, and changed-file overlap with another active PR that truly owns the same path. +`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 **after #395**, it fails on missing metadata, wrong-owner edits, and changed-file overlap with another active PR that truly owns the same path. A pre-policy PR (up to #395) gets **nonblocking findings** to avoid abruptly halting the current ENGINE/FAT branches. 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. +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 +```text WORKSTREAM: GUI | ENGINE | INTEGRATOR | FAT BASE main SHA: PR / head SHA: @@ -47,7 +47,7 @@ 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. From 926134260e673a95605f37d5c8ad69f168c33bf9 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:59:22 +0700 Subject: [PATCH 05/13] chore(coord): PR template requires owner metadata, latest-main audit and exact-SHA handoff --- .github/PULL_REQUEST_TEMPLATE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..0b59b7d1e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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) + + + +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: + +Remove the parked marker only after an owner-scoped diff and conflict audit. From 99a89e28869a02fafe5cad2e7aa8557d4f92d681 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 02:59:41 +0700 Subject: [PATCH 06/13] docs(agents): bind all GUI ENGINE integrator FAT threads to issue #397 ownership gate --- AGENTS.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6c65e2fcb..17fc6f631 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `` while extracting unique verified changes. Pre-policy PRs #395 and earlier receive warnings until reconciled; this is not an approval 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.** From f71dd08a76990a2e1e397b8898665c59ade5b27b Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:00:27 +0700 Subject: [PATCH 07/13] ci(coord/native): fail ownership conflicts before JUCE checkout, reuse existing Windows job --- .github/workflows/p1-windows.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 871c4955a..350816501 100644 --- a/.github/workflows/p1-windows.yml +++ b/.github/workflows/p1-windows.yml @@ -59,6 +59,7 @@ concurrency: permissions: contents: read + pull-requests: read jobs: windows-build: @@ -66,6 +67,11 @@ jobs: 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 @@ -100,6 +106,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' From 975e27c73d678fc217189609d172985ee53b33f4 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:00:43 +0700 Subject: [PATCH 08/13] ci(coord/gui): run same cheap PR collision gate before Chromium, without new workflows --- .github/workflows/ui-smoke.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ui-smoke.yml b/.github/workflows/ui-smoke.yml index c04be840b..f5c80a7d9 100644 --- a/.github/workflows/ui-smoke.yml +++ b/.github/workflows/ui-smoke.yml @@ -19,6 +19,8 @@ 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' @@ -37,6 +39,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 +57,7 @@ concurrency: permissions: contents: read + pull-requests: read jobs: frontend: @@ -61,6 +66,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 }} + 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 +89,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) From 9b494dbdaee8063d1e2bc50340e4fae059766088 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:07:26 +0700 Subject: [PATCH 09/13] ci(coord): require strict owner checks on legacy PR promotion to ready review Draft historical branches stay warning-only while being reconciled; ready_for_review reruns existing scoped Windows/Chromium checks and must meet file ownership. Guard overlapping shared contract tests among same-lane agents too. --- .github/workflows/p1-windows.yml | 1 + .github/workflows/ui-smoke.yml | 1 + AGENTS.md | 2 +- docs/workstreams/MULTI_AGENT_COORDINATION.md | 2 +- scripts/check_workstream_coordination.mjs | 4 ++-- tests/workstream_coordination_contract.test.mjs | 17 ++++++++++++++++- 6 files changed, 22 insertions(+), 5 deletions(-) diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 350816501..009e81ed9 100644 --- a/.github/workflows/p1-windows.yml +++ b/.github/workflows/p1-windows.yml @@ -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/**' diff --git a/.github/workflows/ui-smoke.yml b/.github/workflows/ui-smoke.yml index f5c80a7d9..ecf320484 100644 --- a/.github/workflows/ui-smoke.yml +++ b/.github/workflows/ui-smoke.yml @@ -26,6 +26,7 @@ on: - '.github/workflows/ui-smoke.yml' - '.github/workflows/pages-publish.yml' pull_request: + types: [opened, reopened, synchronize, ready_for_review] paths: - 'web/**' - 'integration/console-v6/**' diff --git a/AGENTS.md b/AGENTS.md index 17fc6f631..f0bb22c6a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ Before touching ArSonMix code, read [workstream ownership and collaboration cont - **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 `` while extracting unique verified changes. Pre-policy PRs #395 and earlier receive warnings until reconciled; this is not an approval to merge conflicting code. One exact-SHA integrator gates a Windows EXE on real native PCM + visual parity + FAT; missing hardware evidence is PENDING. +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 `` while extracting unique verified changes. Pre-policy PRs #395 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.** diff --git a/docs/workstreams/MULTI_AGENT_COORDINATION.md b/docs/workstreams/MULTI_AGENT_COORDINATION.md index 7ae1e3238..14ac33cc9 100644 --- a/docs/workstreams/MULTI_AGENT_COORDINATION.md +++ b/docs/workstreams/MULTI_AGENT_COORDINATION.md @@ -32,7 +32,7 @@ Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number whe `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 **after #395**, it fails on missing metadata, wrong-owner edits, and changed-file overlap with another active PR that truly owns the same path. -A pre-policy PR (up to #395) gets **nonblocking findings** to avoid abruptly halting the current ENGINE/FAT branches. 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. +A pre-policy **DRAFT** PR (up to #395) 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. diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs index bed308c7d..8182d34b4 100644 --- a/scripts/check_workstream_coordination.mjs +++ b/scripts/check_workstream_coordination.mjs @@ -50,7 +50,7 @@ export function metadata(body = '', headRef = '') { } export function audit({pr, files, others = [], filesByPR = {}}) { const current = metadata(pr.body || '', pr.head?.ref || pr.headRef || ''); - const legacy = pr.number <= POLICY_EPOCH_PR; + const legacy = pr.number <= POLICY_EPOCH_PR && pr.draft === true; const errors = [], warnings = []; const changed = new Set(files); const owners = new Set([...changed].map(ownerOf).filter(Boolean)); @@ -76,7 +76,7 @@ export function audit({pr, files, others = [], filesByPR = {}}) { // that edited somebody else's files are reported, not allowed to block. const activeShared = shared.filter(f => { const owner = ownerOf(f); - return owner && owner === current.owner && owner === peer.inferred; + return peer.inferred === current.owner && (!owner || owner === current.owner); }); if (activeShared.length) { errors.push('ACTIVE COLLISION with PR #' + other.number + ' (' + diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs index 38400d08b..11ec6c0da 100644 --- a/tests/workstream_coordination_contract.test.mjs +++ b/tests/workstream_coordination_contract.test.mjs @@ -97,18 +97,33 @@ test('active same-owner native bridge collisions ARE blockers',()=>{ assert.equal(result.activeCollisions,1); }); test('pre-policy PRs remain report-only during migration, not retroactively blocked',()=>{ - const old={number:POLICY_EPOCH_PR,head:{ref:'integration/old'},body:''}; + const old={number:POLICY_EPOCH_PR,draft:true,head:{ref:'integration/old'},body:''}; const result=check(old,['src/LiveAudioEngine.h']); assert.equal(result.ok,true); assert.equal(result.legacy,true); assert.match(result.warnings.join(' '),/LEGACY migration/); }); +test('legacy PR becomes strictly checked on ready-for-review promotion',()=>{ + const old={number:POLICY_EPOCH_PR,draft:false,head:{ref:'integration/old'},body:''}; + const result=check(old,['src/LiveAudioEngine.h']); + assert.equal(result.ok,false); + assert.match(result.errors.join(' '),/arsonmix-workstream/); +}); +test('same-owner shared contract/test files cannot be edited in parallel',()=>{ + const a=pr(405,'ENGINE','engine/route'); + const b=pr(408,'ENGINE','engine/latency'); + const x=check(a,['tests/engine_contract_test.mjs'],[b], + {'408':['tests/engine_contract_test.mjs']}); + assert.equal(x.ok,false); + assert.match(x.errors.join(' '),/ACTIVE COLLISION/); +}); test('coordinator uses existing native + Chromium CI, not a fifth workflow',()=>{ const native=readFileSync('.github/workflows/p1-windows.yml','utf8'); const ui=readFileSync('.github/workflows/ui-smoke.yml','utf8'); for(const text of [native,ui]){ assert.match(text,/scripts\/check_workstream_coordination\.mjs --pr/); assert.match(text,/pull-requests: read/); + assert.match(text,/ready_for_review/); assert.match(text,/GH_TOKEN: \$\{\{ github\.token \}\}/); } const guide=readFileSync('AGENTS.md','utf8'); From 0248a54accf072eb92b02358aee5cad94cb9d2d7 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:08:54 +0700 Subject: [PATCH 10/13] M2.5 reconcile #401 into sole #400 preflight: engine-domain locks, reject alternate GUI, grandfather existing PRs --- scripts/check_workstream_coordination.mjs | 51 +++++++++++++++++-- .../workstream_coordination_contract.test.mjs | 37 ++++++++++++++ 2 files changed, 84 insertions(+), 4 deletions(-) diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs index 8182d34b4..df85fee18 100644 --- a/scripts/check_workstream_coordination.mjs +++ b/scripts/check_workstream_coordination.mjs @@ -5,7 +5,7 @@ // New PRs fail closed on unowned production paths or active same-owner collisions. import { pathToFileURL } from 'node:url'; -export const POLICY_EPOCH_PR = 395; // Earlier PRs are reported, not retroactively failed. +export const POLICY_EPOCH_PR = 399; // Existing #396/#398 are legacy; new #400+ are strict. export const WORKSTREAMS = Object.freeze(['GUI', 'ENGINE', 'INTEGRATOR', 'FAT']); export function ownerOf(path) { @@ -37,6 +37,29 @@ export function ownerOf(path) { return 'ENGINE'; return null; // docs / tests / independent CI fixtures are shared, read-only contracts. } +// Fine-grained subsystems within a workstream. Different filenames can +// still implement a SECOND audio callback or GUI-native reducer. The owning +// PR must coordinate an entire production domain, not merely one path. +export function runtimeDomain(path) { + if (path.startsWith('engine/') || + /^src\/(?:LiveAudioEngine|LiveDryRoutingLab|ConsoleLiveBridgeV6|ApprovedNativeV8Projection|NativeVerifiedSourcePatch)\./.test(path)) + return 'engine-pcm'; + if (/^web\/approved-native-(?:bridge|contract|m2-state)\.js$/.test(path) || + path === 'scripts/build_approved_native_gui.py') + return 'approved-native-bridge'; + if (path === 'src/Main.cpp' || + /^src\/ApprovedConsole.*\.(?:h|cpp)$/.test(path)) + return 'native-host-dispatch'; + if (path.startsWith('site/preview') || path === 'scripts/build_pages.py') + return 'approved-visual'; + if (/^scripts\/(?:check_console_puzzle|check_approved_native_gui_release)\.mjs$/.test(path)) + return 'release-admission'; + if (path.startsWith('.github/workflows/') || + path === 'AGENTS.md' || path === 'scripts/check_workstream_coordination.mjs') + return 'coordination-policy'; + return null; +} + export function metadata(body = '', headRef = '') { const owner = body.match(//i)?.[1]?.toUpperCase() || null; const issue = Number(body.match(//i)?.[1] || 0); @@ -48,12 +71,18 @@ export function metadata(body = '', headRef = '') { if (!inferred && /^work\/integration-fat/.test(headRef)) inferred = 'FAT'; return {owner, inferred, issue, parked}; } -export function audit({pr, files, others = [], filesByPR = {}}) { +export function audit({pr, files, others = [], filesByPR = {}, fileStatuses = {}}) { const current = metadata(pr.body || '', pr.head?.ref || pr.headRef || ''); const legacy = pr.number <= POLICY_EPOCH_PR && pr.draft === true; const errors = [], warnings = []; const changed = new Set(files); const owners = new Set([...changed].map(ownerOf).filter(Boolean)); + // Reject a NEW alternate mixer renderer; deleting its old archive is fine. + for(const path of changed) { + if(/^web/console-native.(?:html|js|css)$/.test(path) && + fileStatuses[path] !== 'removed') + errors.push('ALTERNATE GUI ' + path + ' is forbidden; only /preview/ is approved.'); + } if (!current.owner) errors.push('Declare in PR body'); if (!current.issue) errors.push('Declare (or linked workstream issue) in PR body'); if (current.parked) errors.push('PR is PARKED; remove parked marker only after owner reconciliation'); @@ -84,8 +113,21 @@ export function audit({pr, files, others = [], filesByPR = {}}) { (activeShared.length > 8 ? ' + ' + (activeShared.length - 8) + ' more' : '') + '. Consolidate into ONE owner branch or park the superseded PR.'); } else { - warnings.push('PR #' + other.number + ' also edits ' + shared.length + + if(shared.length)warnings.push('PR #' + other.number + ' also edits ' + shared.length + ' path(s) outside its declared file owner; do not merge it raw.'); + // Exact-path detection alone misses concurrent engine edits in + // different files. Keep domains narrow so CMake/policy is not confused + // with PCM/renderer ownership and existing legitimate owners can work. + if(current.owner && current.owner===peer.inferred) { + const myDomains=new Set([...changed].filter(f=>ownerOf(f)===current.owner) + .map(runtimeDomain).filter(Boolean)); + const competing=(filesByPR[other.number]||[]).find(f=> + ownerOf(f)===current.owner && myDomains.has(runtimeDomain(f)) && + !changed.has(f)); + if(competing)errors.push('ACTIVE DOMAIN COLLISION with PR #' + other.number + + ': ' + runtimeDomain(competing) + ' (' + competing + + '). Distinct files are still ONE runtime subsystem; join the owner PR.'); + } } } if (legacy && errors.length) { @@ -144,7 +186,8 @@ export async function auditGitHub({repo,number,token}) { .map(f=>f.filename); })); } - return audit({pr,files:files.map(f=>f.filename),others,filesByPR}); + return audit({pr,files:files.map(f=>f.filename),others,filesByPR, + fileStatuses:Object.fromEntries(files.map(f=>[f.filename,f.status]))}); } async function main() { const args=process.argv.slice(2); diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs index 11ec6c0da..183e058d5 100644 --- a/tests/workstream_coordination_contract.test.mjs +++ b/tests/workstream_coordination_contract.test.mjs @@ -117,6 +117,43 @@ test('same-owner shared contract/test files cannot be edited in parallel',()=>{ assert.equal(x.ok,false); assert.match(x.errors.join(' '),/ACTIVE COLLISION/); }); +test('new ENGINE branch cannot duplicate native PCM using DIFFERENT filenames',()=>{ + const owner=pr(266,'ENGINE','milestone/m5-native'); + const newcomer=pr(420,'ENGINE','engine/split-work'); + const result=check(newcomer,['engine/core/BrandNewCallback.h'],[owner], + {'266':['src/LiveAudioEngine.h','engine/core/DynamicAcceptedSession.h']}); + assert.equal(result.ok,false); + assert.match(result.errors.join(' '),/ACTIVE DOMAIN COLLISION.*engine-pcm/); +}); +test('new bridge PR cannot fork JS state into another filename',()=>{ + const newBridge=pr(421,'INTEGRATOR','integration/new-bridge'); + const existing=pr(396,'INTEGRATOR','integration/m3-gestures'); + const result=check(newBridge,['web/approved-native-m2-state.js'],[existing], + {'396':['web/approved-native-bridge.js']}); + assert.equal(result.ok,false); + assert.match(result.errors.join(' '),/ACTIVE DOMAIN COLLISION.*approved-native-bridge/); +}); +test('policy and native host stay separate domains despite same INTEGRATOR owner',()=>{ + const newcomer=pr(422,'INTEGRATOR','coord/governance'); + const owner=pr(396,'INTEGRATOR','integration/gestures'); + const result=check(newcomer,['.github/workflows/p1-windows.yml'],[owner], + {'396':['web/approved-native-bridge.js']}); + assert.equal(result.ok,true); +}); +test('new alternate GUI is blocked but retiring old renderer is permitted',()=>{ + const author=pr(423,'GUI','gui/cleanup'); + assert.equal(check(author,['web/console-native.html']).ok,false); + assert.equal(audit({pr:author,files:['web/console-native.html'], + fileStatuses:{'web/console-native.html':'removed'}}).ok,true); +}); +test('existing #396/#398 remain advisory, first strict PR is #400',()=>{ + assert.equal(POLICY_EPOCH_PR,399); + assert.equal(check(pr(398,'INTEGRATOR','integration/old'), + ['src/LiveAudioEngine.h']).ok,true); + assert.equal(check(pr(400,'INTEGRATOR','integration/new'), + ['src/LiveAudioEngine.h']).ok,false); +}); + test('coordinator uses existing native + Chromium CI, not a fifth workflow',()=>{ const native=readFileSync('.github/workflows/p1-windows.yml','utf8'); const ui=readFileSync('.github/workflows/ui-smoke.yml','utf8'); From 97f0403cf6aa12bdccdc9d3a653a9ed968f1cb39 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:10:26 +0700 Subject: [PATCH 11/13] M2.5: repair escaped regex in GUI exclusion preflight (no extra workflow) --- scripts/check_workstream_coordination.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs index df85fee18..09062af8c 100644 --- a/scripts/check_workstream_coordination.mjs +++ b/scripts/check_workstream_coordination.mjs @@ -79,7 +79,7 @@ export function audit({pr, files, others = [], filesByPR = {}, fileStatuses = {} const owners = new Set([...changed].map(ownerOf).filter(Boolean)); // Reject a NEW alternate mixer renderer; deleting its old archive is fine. for(const path of changed) { - if(/^web/console-native.(?:html|js|css)$/.test(path) && + if(['web/console-native.html','web/console-native.js','web/console-native.css'].includes(path) && fileStatuses[path] !== 'removed') errors.push('ALTERNATE GUI ' + path + ' is forbidden; only /preview/ is approved.'); } From b64153009d28f6a714d65eeaac790ef90adb935e Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:12:30 +0700 Subject: [PATCH 12/13] M2.5: block distinct-file same-domain production duplicates; preserve grandfathered draft PRs --- scripts/check_workstream_coordination.mjs | 3 ++- tests/workstream_coordination_contract.test.mjs | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs index 09062af8c..a92f7b531 100644 --- a/scripts/check_workstream_coordination.mjs +++ b/scripts/check_workstream_coordination.mjs @@ -100,7 +100,8 @@ export function audit({pr, files, others = [], filesByPR = {}, fileStatuses = {} if (peer.parked) continue; const shared = [...changed].filter(f => (filesByPR[other.number] || []).includes(f)); - if (!shared.length) continue; + // No exact overlap is NOT grounds to skip: two different files can + // still create two native PCM/bridge implementations in one domain. // The sole authorized owner must be free to progress. Legacy branches // that edited somebody else's files are reported, not allowed to block. const activeShared = shared.filter(f => { diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs index 183e058d5..a8aa5f019 100644 --- a/tests/workstream_coordination_contract.test.mjs +++ b/tests/workstream_coordination_contract.test.mjs @@ -148,7 +148,7 @@ test('new alternate GUI is blocked but retiring old renderer is permitted',()=>{ }); test('existing #396/#398 remain advisory, first strict PR is #400',()=>{ assert.equal(POLICY_EPOCH_PR,399); - assert.equal(check(pr(398,'INTEGRATOR','integration/old'), + assert.equal(check({...pr(398,'INTEGRATOR','integration/old'),draft:true}, ['src/LiveAudioEngine.h']).ok,true); assert.equal(check(pr(400,'INTEGRATOR','integration/new'), ['src/LiveAudioEngine.h']).ok,false); From c1afbec998f36c82197dcc6ac765cff7085e3644 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 5 Nov 2026 03:15:20 +0700 Subject: [PATCH 13/13] M2.5: align multi-agent handoff with #400 strict epoch and whole-runtime domain protection --- AGENTS.md | 2 +- docs/workstreams/MULTI_AGENT_COORDINATION.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f0bb22c6a..7b0b210e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ Before touching ArSonMix code, read [workstream ownership and collaboration cont - **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 `` while extracting unique verified changes. Pre-policy PRs #395 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. +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 `` 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.** diff --git a/docs/workstreams/MULTI_AGENT_COORDINATION.md b/docs/workstreams/MULTI_AGENT_COORDINATION.md index 14ac33cc9..0db65ab54 100644 --- a/docs/workstreams/MULTI_AGENT_COORDINATION.md +++ b/docs/workstreams/MULTI_AGENT_COORDINATION.md @@ -30,9 +30,9 @@ Allowed owners: GUI, ENGINE, INTEGRATOR, FAT. Use the technical issue number whe ## 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 **after #395**, it fails on missing metadata, wrong-owner edits, and changed-file overlap with another active PR that truly owns the same path. +`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 #395) 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. +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.