Structure for features

[JaclynCodes]

This pull request introduces significant improvements to project documentation, CI/CD workflows, and testing configuration, with a focus on scientific rigor, maintainability, and automation. The README is completely restructured to emphasize the scientific foundation, interface-first design, and a documentation-as-code testing philosophy. CI workflows are enhanced with caching, markdown linting, and more robust parsing. Testing infrastructure is strengthened with stricter pytest configuration and support for parallel execution.

Documentation and Scientific Foundation:

• Major rewrite and expansion of README.md to clearly articulate the scientific motivation (acoustic energy density), interface-first API design, documentation-as-code testing approach, phased roadmap, and scientific references. The README now includes diagrams, example code, and detailed explanations of project phases and scientific background. [1] [2] [3] [4] [5]
• Added a new .markdownlint.json configuration to enforce markdown style and code block language tags, improving documentation quality.
• Clarified technical precedence in the architecture document.

CI/CD and Workflow Enhancements:

• Updated .github/workflows/blank.yml to enable pip caching for Python dependencies, optimize test runs, and add a new markdown linting job using markdownlint-cli2-action. [1] [2] [3]
• Changed the deployment workflow trigger branch from canary to main in .github/workflows/static.yml for more standard release management.
• Improved robustness and accuracy of task parsing in the iteration status email workflow by refining grep patterns and making dashboard links point to the exact commit SHA. [1] [2]

Testing Infrastructure:

• Enhanced pytest.ini with strict marker/config enforcement, cache directory, and explicit test markers for better test organization and error detection.
• Added pytest-xdist to setup.py for parallel test execution, improving CI speed.

These changes collectively improve the project's scientific clarity, documentation quality, workflow automation, and testing reliability.

---

Summary by cubic

Implements core audio and energy modules with a clean public API, and upgrades CI/testing and documentation to lay a reliable, science-first foundation.

• New Features

  • Audio: load_audio, save_audio, normalize_peak, to_mono, frame_signal.
  • Energy: acoustic_intensity_proxy, frame_energy_density, energy_decomposition_proxy.
  • Top-level exports added for the new helpers.
  • README rebuilt with scientific background and interface-first API; architecture doc clarified.

• CI/CD and Testing

  • GitHub Actions: pip caching, new markdown lint job (markdownlint-cli2), Pages deploy branch switched to main.
  • Iteration-status emails workflow: safer grep patterns and dashboard link pinned to commit SHA.
  • Pytest: strict markers/config, cache dir, and parallel runs via pytest-xdist.
  • Extensive tests added for audio, energy, public API exports, and workflow integration; dependencies updated and pinned (librosa, soundfile, numpy) with a libsndfile CVE note.

^{Written for commit d04f63b. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/symphonic_joules/audio.py">

<violation number="1" location="src/symphonic_joules/audio.py:91">
P2: save_audio now requires a different channel orientation than load_audio returns, so a common load→save flow will write with swapped dimensions or fail. Either accept channel‑first input from load_audio or convert it before writing.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/symphonic_joules/audio.py">

<violation number="1" location="src/symphonic_joules/audio.py:91">
P2: save_audio no longer handles the channels-first arrays produced by load_audio, so saving multi-channel output from this module will write incorrect audio unless callers manually transpose. This is an API inconsistency/regression in the module.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[JaclynCodes]

gh pr checkout 178

[JaclynCodes]

bcbe448#r2729304332

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/symphonic_joules/audio.py">

<violation number="1" location="src/symphonic_joules/audio.py:92">
P2: The auto-transpose heuristic assumes samples > channels. For short multi‑channel arrays where n_samples < n_channels, it will transpose valid (n_samples, n_channels) data and silently save corrupted audio. Consider requiring explicit orientation or validating shape instead of guessing.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: The auto-transpose heuristic assumes samples > channels. For short multi‑channel arrays where n_samples < n_channels, it will transpose valid (n_samples, n_channels) data and silently save corrupted audio. Consider requiring explicit orientation or validating shape instead of guessing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/symphonic_joules/audio.py, line 92:

<comment>The auto-transpose heuristic assumes samples > channels. For short multi‑channel arrays where n_samples < n_channels, it will transpose valid (n_samples, n_channels) data and silently save corrupted audio. Consider requiring explicit orientation or validating shape instead of guessing.</comment>

<file context>
@@ -86,9 +87,11 @@ def save_audio(path: str, y: np.ndarray, sr: int) -> None:
-        # Caller must provide waveform in (n_samples, n_channels) orientation.
+        # Transpose if multi-channel audio is in (n_channels, n_samples) format
+        # to match soundfile's expected (n_samples, n_channels) format
+        if y.ndim == 2 and y.shape[0] < y.shape[1]:
+            y = y.T
+            
</file context>