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. diff --git a/.github/workflows/p1-windows.yml b/.github/workflows/p1-windows.yml index 871c4955a..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/**' @@ -59,6 +60,7 @@ concurrency: permissions: contents: read + pull-requests: read jobs: windows-build: @@ -66,6 +68,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 +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' diff --git a/.github/workflows/ui-smoke.yml b/.github/workflows/ui-smoke.yml index c04be840b..ecf320484 100644 --- a/.github/workflows/ui-smoke.yml +++ b/.github/workflows/ui-smoke.yml @@ -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 }} + 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) diff --git a/AGENTS.md b/AGENTS.md index 6c65e2fcb..7b0b210e2 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 #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 new file mode 100644 index 000000000..0db65ab54 --- /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 **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. diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs new file mode 100644 index 000000000..a92f7b531 --- /dev/null +++ b/scripts/check_workstream_coordination.mjs @@ -0,0 +1,217 @@ +#!/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 = 399; // Existing #396/#398 are legacy; new #400+ are strict. +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. +} +// 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); + 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 = {}, 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','web/console-native.js','web/console-native.css'].includes(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'); + 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)); + // 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 => { + const owner = ownerOf(f); + return peer.inferred === current.owner && (!owner || owner === current.owner); + }); + 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 { + 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) { + 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, + fileStatuses:Object.fromEntries(files.map(f=>[f.filename,f.status]))}); +} +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. + }); +} diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs new file mode 100644 index 000000000..a8aa5f019 --- /dev/null +++ b/tests/workstream_coordination_contract.test.mjs @@ -0,0 +1,169 @@ +// 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,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('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'),draft:true}, + ['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'); + 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'); + assert.match(guide,/MULTI_AGENT_COORDINATION\.md/); + assert.match(guide,/#397/); +});