Document the real Spoken Audio Node migration state, and fix the CI that hid it

[MaximillianGroup]

Scope note: this was titled docs:, which Copilot correctly flagged as wrong. It touches runtime PHP and JS as well as CI config — see What this actually changes below. Retitled rather than left misleading.

The review was right on both counts: this repository was byte-identical to before, and the boundary file asserted a hold on ADRs that were not on the registry's default branch. This PR does not pretend otherwise.

It does not build the Spoken Audio Node. It states precisely what has moved, what has not, and what each remaining step is waiting on — and it does that instead of inventing a service.

What this actually changes

Area	Files
Boundary documentation	.github/instructions/starmus-boundary.md
Runtime PHP	StarmusAssetLoader.php, StarmusUiPackageResolver.php, StarmusProsodyPlayer.php, StarmusAfricaBandwidthService.php
Runtime JS	starmus-integrator.js, starmus-main.js, starmus-recorder.js
Template	starmus-audio-editor-ui.php
CI config	.wp-env.json

Why the Node is not in this PR

The Capture → Ingestion contract lists four things as owed: the endpoint path and auth model, the upload metadata key set, the acknowledgement and error envelope, and confirmation that the consumer verifies sha256 as the producer sends.

Writing endpoint paths, field names and status codes for a service that does not exist would produce exactly the fabricated identifiers this organisation has shipped before. The contract says no repository implements a guess at those; that rule applies to me.

What actually changed on main, and why it matters

7a61de8 landed the manifest-driven UI package boundary (starmus-ui-packages.json + StarmusUiPackageResolver). That is the mechanism that lets this plugin stop shipping its own copy of the capture JS and consume the built capture UI package instead. It is the precondition for the two removals below, and it is done. Branch is merged up to current main.

The two removals, and what genuinely blocks them

1. The nineteen duplicated JS files in src/js/ — fifteen are diverged copies of files in the capture UI package. Blocked on the capture UI package being resolvable through the manifest as a published artifact rather than a sibling checkout.

2. The prosody assets and their prosodyScript / prosodyStyle manifest surface. Blocked on the elicitation pacing package being publishable — StarmusProsodyPlayer.php enqueues them today and the resolver needs a URL to point at instead.

I deliberately did not delete either set. StarmusProsodyPlayer would fatal and the paced reader would vanish from every live page. Deleting files to make a diff look like progress, and breaking a shipping product to do it, is worse than saying what is blocked.

Also open

Which repository carries the CMS host product once this one becomes a service — this repo's residue, or a new one. ADR-034 leaves it open on purpose. It wants deciding before files move.

CI

Three failures here are not this PR's and are red on main:

1. Trigger_EthicalCheck — apisec-inc/ethicalcheck-action no longer resolves. #27 replaces it. Not ported here: I could not verify the replacement action resolves, and an unverified uses: in a security workflow is the failure this org has already been bitten by.
2. Lint & Proof Frontend Assets — docs/index.html links to six ../*.html files that are never generated. Neither PR fixes this.
3. build / wordpress-tests — see below.

I did port one line from #27: .wp-env.json was pinned to WordPress 6.4 while the plugin header declares Requires at least: 6.9, so the plugin could never activate in its own test environment. That is fixed here and no-ops once #27 lands.

That fix unmasked a second, previously hidden failure in the same job — details in the PR thread. It is also pre-existing and also not this PR's.

#27 should merge first.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_016cDiLJsQCkPdU4ghzcQSTY

[amazon-q-developer]

This documentation-only PR successfully adds repository boundary documentation for pending ADR-034/035/036. The markdown file is well-structured, clearly communicates the current state versus future state, and appropriately documents the hold on restructuring until ADRs are accepted. No defects found that block merge.

---

You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.

[MaximillianGroup]

CI: four checks red, none of them this PR's

This PR's diff is exactly one new file, .github/instructions/starmus-boundary.md (49 lines of Markdown). It contains no JS, no PHP, no CSS and no workflow change, so it cannot reach any of the four failing checks. Each is pre-existing on main. Standing down on all four rather than widening a documentation-only PR — details and proposed patches below.

1. Trigger_EthicalCheck — the action no longer exists

##[error]Unable to resolve action `apisec-inc/ethicalcheck-action`, not found

The job fails at action resolution, before checkout. Red on main on every scheduled run (.github/workflows/ethicalcheck.yml runs on schedule: '37 9 * * 2') — runs #129, #131, #133, #134, #136 were all failures on main's current HEAD. Not spending the one permitted re-run: the failure is a deterministic registry lookup, and base-branch evidence already establishes it is not this PR's.

Worth a separate decision, not a silent fix: the workflow is an unmodified GitHub starter template. It scans oas-url: "http://netbanking.apisec.ai:8080/v2/api-docs" — apisec's own public demo API, not this repository's — and mails the report to email: "xxx@apisec.ai". It has never tested this codebase. Removing a check named "EthicalCheck" from a security posture is a governance call, so I'm raising it rather than doing it.

2. Lint & Proof Frontend Assets — 164 pre-existing ESLint indent errors

Reproduced locally on this branch, identical count to CI (164 problems (164 errors, 0 warnings)), in five files this PR does not touch:

errors	file
130	src/js/starmus-state-store.js
19	src/js/starmus-enhanced-calibration.js
8	src/js/starmus-recorder.js
4	src/js/starmus-metadata-auto.js
3	src/js/starmus-core.js

All 164 are indent and all are auto-fixable (pnpm run lint:js:fix). Deliberately not run here: four of those five files are among the fifteen that ADR-034 (this PR's subject) says get reconciled against their diverged twins in the capture UI package. Reformatting them now would put a 164-line whitespace diff between the two copies and make that reconciliation materially harder to read. The fix is one command — it belongs in its own PR, before or after the reconciliation, not inside a docs PR.

3. wordpress-tests (8.2, latest) — wp-env never starts

✖ Environment not initialized. Run `wp-env start` first.

wp-env start fails, then env:stop fails on the un-started environment. The Tests workflow has failed on main on every scheduled run for weeks — runs #241 through #258 are all failure on main's current HEAD (11ba108). Environment/infra, not a test regression, and not this PR's.

4. build — one pre-existing PHPStan error

src/services/StarmusR2DirectService.php:255
Strict comparison using === between 'https://cdn…' and '' will always evaluate to false.
🪪 identical.alwaysFalse

PHPDoc declares the value non-empty-string, so the === '' guard is statically dead. Proposed patch, for whoever owns that file: either correct the PHPDoc to allow '' if the runtime value really can be empty, or drop the dead comparison. Both are one line, and both are in PHP this PR does not touch.

Summary

Nothing here blocks review of the ADR content. Items 1–4 are four separate pre-existing repo-health issues, each wanting its own small PR. Starisian-Technologies/sparxstar-architecture-governance-registry#41 — which carries the actual decisions this PR points at — is green.

---

Generated by Claude Code

[Copilot]

🟡 Changes recommended

The new instruction doc contains a few clarity/traceability gaps (undefined acronym and missing decision-record linkage) that should be corrected to avoid future ambiguity.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new GitHub instruction document that records this repository’s designated role (“Spoken Audio Node”) under ADR-034 and explicitly places a hold on restructuring work until ADR-034/035/036 are accepted, including a checklist of what ownership shifts on acceptance.

Changes:

• Add .github/instructions/starmus-boundary.md documenting the repository boundary, hold condition, and post-acceptance ownership split.
• Record specific scope items that move out of this repo on ADR-034 acceptance (CMS UI/templates/recorder/CSS/transcript-related concerns).
• Record constraints tied to ADR-035/036 (capture profile required for acoustic measurement; no import-path transcoding).

File summaries

File	Description
.github/instructions/starmus-boundary.md	New boundary/hold instruction doc for ADR-034/035/036 designation and planned responsibility split.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[MaximillianGroup]

Correct that it was undefined, and addressed in f3a0e7c — but deliberately not by spelling it out, for two reasons worth recording:

1. I don't have the expansion from a source I can verify. Writing one from inference is exactly the failure mode this repository's own governance instructions forbid, and a plausible-looking wrong expansion in an instruction file is worse than an unexpanded acronym — agents and contributors would propagate it.
2. This repository is not ESU's home. A definition maintained in two places drifts, which is the same defect ADR-034 is filed to fix one level up.

So the file now scopes ESU by what it owns, in one clause, and says where the expansion lives:

The reviewed transcript and any translation are ESU's records — ESU being the platform component that holds reviewed transcript, translation and linguistic-interpretation records, as ADR-034 and ADR-036 assign them. Its name is not expanded here: this repository is not ESU's home, and a definition maintained in two places drifts. Take the expansion from ESU's own repository or from the governance registry, not from this file.

That gives a new contributor what they actually need at this boundary — what ESU owns and why it isn't ours — without minting an unverified identifier. Same treatment applied to the identical sentence on Starisian-Technologies/sparxstar-starmus-ui#5.

If the canonical expansion is recorded somewhere I can read, the better fix is a glossary entry in the governance registry that both files point at, rather than the string being copied into each repository. Happy to open that.

---

Generated by Claude Code

[Copilot]

🟢 Approval recommended

Documentation-only addition with internally consistent, verifiable statements and no code/config/build impact.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Document Spoken Audio Node migration boundaries and blockers

📝 Documentation 🕐 10-20 Minutes

AI Description

• Defines planned Spoken Audio Node ownership and excluded CMS and capture responsibilities.
• Records completed boundary work and explicit blockers for remaining migration steps.
• Links governing ADRs and seam contracts without duplicating their rationale.

Diagram

graph TD
  G["Governance Registry"] -->|"sets boundaries"| R["Current CMS Repo"] -->|"migrates toward"| N["Planned Audio Node"] -->|"preserves bytes"| S[("Object Storage")]
  C["Capture UI"] -->|"uploads assets"| N -->|"serves records"| E["ESU Records"]

Loading

High-Level Assessment

The documentation-first approach is appropriate because required contracts, published UI artifacts, and CMS repository placement remain unresolved. Keeping repository-specific role and migration status here while linking to the governance registry avoids duplicating rationale or fabricating service interfaces; implementing or deleting assets now would risk breaking the shipping product.

Files changed (1) +83 / -0

Documentation (1) +83 / -0

starmus-boundary.mdDefine Spoken Audio Node boundaries and migration blockers +83/-0

Define Spoken Audio Node boundaries and migration blockers

• Adds a repository boundary document linking ADR-034, ADR-035, ADR-036, and the governing seam contracts. It distinguishes completed package-boundary work from blocked JavaScript, prosody, ingestion-service, and CMS-host migrations, while recording ownership rules that already apply.

.github/instructions/starmus-boundary.md

[Copilot]

🔵 Needs a closer look

The new boundary doc references “ESU” without the previously-agreed scoping guidance, reducing clarity for new contributors.

Review details

Suppressed comments (1)

.github/instructions/starmus-boundary.md:28

• “ESU” is referenced as an acronym without scoping guidance in this version of the boundary doc. Given the file’s goal is to be self-contained for contributors, add a short clause that defines ESU by responsibility (without expanding the name here) and points readers to the governance registry/ESU repo for the canonical expansion.

**It does not capture.** Browser microphone access, local and offline handling,
the chunked-upload client and capture UX are the capture UI package's. The
reviewed transcript and its translation are ESU's; acoustic measurement is
ours, and interpreting what a measurement means is ESU's.

• Files reviewed: 7/9 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

It reintroduces an undefined “ESU” reference in the new boundary doc and includes non-doc code formatting edits that don’t match the PR’s docs-only scope.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

.github/instructions/starmus-boundary.md:28

• “ESU” is referenced without any local scoping/definition, which makes the boundary statement ambiguous for contributors who aren’t already familiar with the platform components. Prior threads noted this should be clarified without inventing an expansion; add a short clause explaining what ESU owns and where the canonical expansion lives (governance registry / ESU repo).

**It does not capture.** Browser microphone access, local and offline handling,
the chunked-upload client and capture UX are the capture UI package's. The
reviewed transcript and its translation are ESU's; acoustic measurement is
ours, and interpreting what a measurement means is ESU's.

• Files reviewed: 7/9 changed files
• Comments generated: 1
• Review effort level: Lite

[MaximillianGroup]

Trigger_EthicalCheck is failing, and it is not this PR's — but it needs your attention anyway

What's failing: the Trigger_EthicalCheck job, at workflow-preparation time:

##[error]Unable to resolve action `apisec-inc/ethicalcheck-action`, not found

Why it isn't this PR's. The reference lives in .github/workflows/ethicalcheck.yml at line 57 on main:

uses: apisec-inc/ethicalcheck-action@005fac321dd843682b1af6b72f30caaf9952c641

This PR's diff touches nine files — PHP, JS and one instruction doc — and not a single file under .github/workflows/. The failure also happens during action resolution, before checkout, so no code in the diff can influence it. It is red on main for the same reason.

No fix ported, deliberately. The action can't be resolved at that SHA — the upstream repository is gone, renamed, or private. I am not substituting a replacement action name: guessing at a third-party action reference is exactly the fabricated-identifier failure the org rules prohibit, and a wrong uses: in a security workflow is worse than a missing one. Fixing this needs someone who knows what happened to apisec-inc/ethicalcheck-action — whether it moved, or whether the scan should be retired.

The part that matters more than the red check

This is a security-scanning workflow that has been silently non-functional. The repository has an API security scan configured, a SARIF upload step, and SecurityEvents: write permission — and it has been producing no findings, because it never runs. A red X on PRs is the visible symptom; the invisible one is that nobody has been getting API security results from this repo for however long the action has been unresolvable.

Two things worth deciding:

1. Where did apisec-inc/ethicalcheck-action go? If it moved, pin the new reference by SHA. If the product is gone, remove the workflow rather than leaving a permanently-red check that trains everyone to ignore failures.
2. Was anything relying on those SARIF results? If this was the repo's only API-surface scan, removing it leaves a real gap, not just a tidier check list.

I've left the workflow untouched. It is not this PR's to change, and the right change depends on an answer I don't have.

---

Separately, c8b6465 addressed the two Copilot findings on this PR: qualified the global built-ins (the flagged rtrim() plus three file_exists(), one json_decode() and two more rtrim() calls the review didn't mention), and scoped ESU in the boundary doc — stating what it owns and where the canonical name lives, without inventing an expansion I can't verify.

---

Generated by Claude Code

[MaximillianGroup]

Correcting the record: the \rtrim() finding was wrong, and so was my fix

An auto-fix commit (bddd1a4) reverted my qualification of rtrim(), file_exists() and json_decode() — while leaving \is_string() and \is_array() qualified. I went looking for why, and the repo's own config answers it. .php-cs-fixer.dist.php line 34:

'native_function_invocation' => ['include' => ['@compiler_optimized'], 'scope' => 'namespaced'],

@compiler_optimized is a specific PHP-CS-Fixer function set: the ones the PHP engine can compile to dedicated opcodes only when called with a leading \. is_array, is_string, defined and sprintf are in it. rtrim, file_exists and json_decode are not — so the fixer strips the backslash from those, deliberately.

So the mix Copilot flagged as an inconsistency is not one. It is a performance rule, enforced by tooling, and it is doing exactly what it was configured to do. Copilot's finding was incorrect; my "fix" extended the error to five more call sites; the fixer caught it. I've merged the revert rather than re-applying anything — the configured tool is the authority on this repo's style, not a reviewer's impression of it or mine.

Worth noting for future reviews in this repo: do not "normalize" function qualification here by eye. Run pnpm run lint / the fixer and let it decide.

build — fix ported from #27 (c1935fe)

Separately, build was failing before any test ran:

Failed to activate plugin. Current WordPress version (6.4) does not meet
minimum requirements for Sparxstar Starmus Audio. The plugin requires
WordPress 6.9.
Error: No plugins activated.

starmus-audio-recorder.php declares Requires at least: 6.9; .wp-env.json pinned core to 6.4. The plugin could never activate in its own test environment. Not this PR's — red on main for the same reason — but #27 already carries the identical one-line fix, so I've ported it rather than wait. It no-ops once #27 merges.

What I did not port, and why

#27 also replaces the dead apisec-inc/ethicalcheck-action with apisec-university/free-API-security-test-action@beta, gated behind APISEC_BASE_URL / APISEC_SPECIFICATION_PATH / APISECU_TOKEN.

I did not port that. I tried to confirm the replacement action resolves, and outbound requests from this environment return 403 from the proxy for both the new reference and the known-dead one — which is not an answer either way. Pushing a uses: I cannot verify into a security workflow is precisely the failure this repo has already been bitten by. #27 authored that change and should carry it.

That also updates my earlier comment: a real fix for Trigger_EthicalCheck does exist, in #27. My earlier note said none did, which was true when I wrote it and is no longer.

Merge order for this repo

#27 first. It fixes Trigger_EthicalCheck, the .wp-env.json version (which I've now duplicated harmlessly), the test.yml matrix, and a wrong CSS path in validate-build.cjs. This PR is a boundary-doc and split change; it should follow.

Still outstanding and not addressed by either PR: docs/index.html links to six ../*.html files that are never generated, so HTML-Proofer fails on main independently.

---

Generated by Claude Code

[Copilot]

🟡 Changes recommended

It introduces an avoidable use function import/style inconsistency in StarmusUiPackageResolver and the PR metadata should be aligned with the fact it touches production runtime code, not just documentation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/js/starmus-recorder.js:58

• PR title/description present this as a documentation-only clarification of migration state, but this PR also changes runtime PHP/JS files (e.g., formatting changes here). To reduce review risk and avoid surprises for deploys, either split the non-doc changes into a separate PR or update the PR title/description to reflect that it touches production code.

• Files reviewed: 8/10 changed files
• Comments generated: 1
• Review effort level: Lite

[MaximillianGroup]

The wp-env fix worked, and it unmasked a second bug in the same job

wp-env start now succeeds — WordPress development site started, ✔ Done! (in 72s). The 6.4-vs-6.9 activation failure is gone.

build still fails, but further along and for a different reason:

> wp-env run tests-cli --env-cwd=wp-content/plugins/starmus-audio-recorder \
    bash -c 'wp plugin activate starmus-audio-recorder && wp plugin list'

OCI runtime exec failed: chdir to cwd
("/var/www/html/wp-content/plugins/starmus-audio-recorder") failed:
no such file or directory
✖ Command failed with exit code 127

Root cause: a folder name confused with a file name

.wp-env.json mounts the plugin as "plugins": ["."] — the repository directory, which is sparxstar-starmus-audio. wp-env mounts a local plugin under its own directory basename, so inside the container the plugin lives at:

/var/www/html/wp-content/plugins/sparxstar-starmus-audio

But package.json line 42 looks for wp-content/plugins/starmus-audio-recorder and activates the slug starmus-audio-recorder. That name is the main PHP file (starmus-audio-recorder.php), not the folder. The two have never matched — the repo follows the org's sparxstar-{product-name} convention while this script was written against the plugin file's name.

This was invisible until now because wp-env start failed on the version check before the test step ever ran. Fixing one exposed the other.

Proposed patch

-"test:integration": "wp-env run tests-cli --env-cwd=wp-content/plugins/starmus-audio-recorder bash -c 'wp plugin activate starmus-audio-recorder && wp plugin list'",
+"test:integration": "wp-env run tests-cli --env-cwd=wp-content/plugins/sparxstar-starmus-audio bash -c 'wp plugin activate sparxstar-starmus-audio && wp plugin list'",

Why I have not pushed it

Two reasons, and I want to be straight about the second.

It is not this PR's, and no fix exists to port. #27 does not touch package.json. The rule I am working to says: for a pre-existing failure in unrelated code with no existing fix, report it with a proposed patch rather than widen the PR. I ported the .wp-env.json line because a verified fix already existed in #27; this one does not, so it belongs in a CI PR, not a boundary-doc one.

And my inference is strong but untested. I am reasoning about how wp-env names its mount from the checkout path in the runner log (/home/runner/work/sparxstar-starmus-audio/sparxstar-starmus-audio) and from "plugins": ["."]. I cannot run Docker here to confirm it. Anyone applying the patch should check the real name first:

pnpm exec wp-env run tests-cli ls wp-content/plugins

Pushing a CI change I cannot execute would just spend another red round guessing. Better to hand over the diagnosis with the one command that settles it.

Also

Copilot flagged unused use function file_exists; / use function json_decode; imports in StarmusUiPackageResolver.php. That is now stale — the auto-fix commit bddd1a4 restored unqualified calls, so those imports are used and the style is uniform. The review raced the fixer.

The PR title and description are updated: it was labelled docs: while touching runtime PHP, JS and CI config, which was a fair catch.

---

Generated by Claude Code

[Copilot]

🟡 Changes recommended

The PR is presented as a docs-only update, but includes unrelated code/config modifications that should be split out or the PR scope/title/description updated to match.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 8/10 changed files
• Comments generated: 1
• Review effort level: Lite