From 29ce37aed5e473d23a7d0aba70572e6db641284f Mon Sep 17 00:00:00 2001 From: Steven Atkinson Date: Sat, 22 Aug 2026 22:46:29 -0700 Subject: [PATCH 1/3] Add release checks and clarify A2 feature fixture --- .agents/skills/release-check/SKILL.md | 206 ++++++++++++++++++ .../skills/release-check/agents/openai.yaml | 4 + docs/index.rst | 2 + docs/release_guarantees.rst | 123 +++++++++++ ...a2_max.nam => wavenet_a2_feature_test.nam} | 4 +- generate_weights_a2.py | 10 +- tools/test/test_container.cpp | 20 +- tools/test/test_get_dsp.cpp | 2 +- 8 files changed, 353 insertions(+), 18 deletions(-) create mode 100644 .agents/skills/release-check/SKILL.md create mode 100644 .agents/skills/release-check/agents/openai.yaml create mode 100644 docs/release_guarantees.rst rename example_models/{wavenet_a2_max.nam => wavenet_a2_feature_test.nam} (99%) diff --git a/.agents/skills/release-check/SKILL.md b/.agents/skills/release-check/SKILL.md new file mode 100644 index 00000000..b20414f2 --- /dev/null +++ b/.agents/skills/release-check/SKILL.md @@ -0,0 +1,206 @@ +--- +name: release-check +description: "Assess a repository against a release checklist or public release-guarantees document, and when fixes are explicitly requested, remediate deficiencies using two coordinated flights of subagents: evidence gathering, then isolated-worktree fixes merged into a user-named development integration branch. Use when asked to qualify, prepare, harden, audit, or make a codebase ready for a release without publishing the release." +--- + +# Release Check + +Qualify a release with evidence, then repair reasonable deficiencies when the +request authorizes fixes, without weakening the release contract. Keep all work +on the user-named development integration branch. This workflow must never +merge to a branch literally named `main`. + +## Establish scope and branch roles + +1. Read repository instructions and inspect status, remotes, branches, + worktrees, version sources, tags, and CI configuration. Do not alter the + user's original checkout. +2. Find the governing criteria in this order: + - a path or checklist supplied by the user; + - `docs/release_guarantees.rst`; + - `RELEASE_GUARANTEES.md`, `RELEASING.md`, or equivalent project docs; + - a checklist explicitly derived with the user when no contract exists. +3. Determine whether the request is assessment-only or explicitly authorizes + remediation. Assessment-only requests must not create branches or commits. +4. Determine and record `target_version`, the base ref, immutable `base_sha`, + and, for remediation, the requested integration ref. Distinguish these + branch roles: + - **base branch**: the branch from which qualification starts; + - **integration branch**: the user-named development branch that receives + all qualification fixes, such as `release-check`; + - **work branches**: short-lived branches in private worktrees used by + remediation agents. +5. Resolve identity from the request and repository evidence. Ask if the target + version, base, or integration branch remains ambiguous. Reject `main` as the + integration target rather than silently substituting another branch. +6. If the intended release includes uncommitted changes, stop and ask for an + immutable committed revision or explicit exclusion of those changes. Do not + silently omit or capture them. +7. Define `qualification_start_sha`, the immutable commit Flight 1 assesses. + For a new integration branch it equals `base_sha`; for an existing + integration branch it is that branch's current `HEAD`; for assessment-only + work it is the commit selected by the user or current repository context. +8. Preserve all pre-existing user changes. Do not stash, discard, commit, move, + reset, or clean them. +9. Treat a draft guarantee policy as candidate criteria only. If it excludes + the target version, do not change its coverage or claim the version is + guaranteed without explicit user authorization. + +## Plan the qualification + +Create a plan with separate assessment, remediation, integration, and final +verification stages. Convert the governing document into atomic criteria with +stable identifiers. Include applicable criteria for: + +- versioning, release scope, and deprecations; +- formatting, compiler warnings, and source hygiene; +- public API and user documentation; +- clean Debug and Release builds, supported build variants, and tests; +- supported platforms, toolchains, architectures, and downstream consumers; +- model/file compatibility and DSP output correctness; +- real-time safety and thread behavior; +- performance and memory regressions; +- dependencies, licenses, and source reproducibility; and +- tag, artifact, and publication readiness. + +Do not create or fail a criterion because a changelog or release-notes file is +absent from the repository. This project uses GitHub-generated release notes; +their generation and publication happen outside the pre-release repository +qualification unless the user explicitly requests a hosted-release check. + +Do not push, tag, create a pull request or hosted release, dispatch remote +workflows, upload packages or artifacts, deploy, sign or notarize artifacts, or +update downstream repositories unless the user separately authorizes those +external changes. + +## Flight 1: independent assessment + +Use subagents for a repository-read-only first flight. Before dispatch, create +one disposable detached worktree per assessor at `qualification_start_sha`. +Place build and test outputs in separately recorded temporary directories +outside the worktree wherever the tools allow it. Forbid tracked changes, +commits, branch/ref changes, and remote mutations. Partition criteria into +bounded, non-overlapping groups and adapt the number of groups to the available +concurrency. A useful partition is: + +1. API documentation, user docs, versioning, and release metadata. +2. builds, CI, unit/integration tests, sanitizers, and consumer compatibility. +3. model compatibility, DSP correctness, real-time safety, and performance. +4. dependencies, licensing, reproducibility, and publishing readiness. + +Give each agent its worktree path, target version, frozen qualification identity, +criteria IDs, and integration branch. Require this result for every criterion: + +- status: `pass`, `fail`, `unknown`, or `not-applicable`; +- concise evidence with file paths, line numbers, commands, or test output; +- the exact deficiency when status is not `pass`; +- a proposed remediation and its validation command; +- dependencies, risk, and whether the environment can verify it. + +Require each assessor to finish with `git status --porcelain` evidence and no +tracked or untracked changes. Before cleanup, inventory ignored files and +delete only explicitly recorded outputs created by the skill after resolving +their exact paths. Never use a broad clean command. Remove only the recorded +disposable worktrees, without force, after findings and outputs are captured. +If unexplained files remain, preserve the worktree and report it. + +Require execution evidence where practical. The existence of a test, workflow, +or documentation setting is not proof that it passes. An unavailable platform +or service is `unknown`, not `pass`. + +## Consolidate and decide + +Wait for all assessment agents, resolve contradictory findings against primary +evidence, and create one qualification ledger containing every criterion. +Summarize the ledger for the user before remediation. For audit, assess, review, +or qualify-only requests, stop here. Continue into remediation only when the +user explicitly asked to fix, prepare, harden, or make the release ready. + +Before remediation, inspect the worktree list. Create a dedicated integration +worktree at an explicit recorded path: create a new integration branch at +`base_sha`, or attach the existing integration branch at +`qualification_start_sha` without overwriting it. If that ref is already +checked out in a user-owned worktree, do not modify or detach it; ask the user +to release it or explicitly authorize use of that exact worktree. Perform every +coordinator branch, commit, and merge operation inside the recorded integration +worktree, never the original checkout. + +Classify failed and unknown criteria as: + +- **fix now**: bounded repository work directly needed to meet the criterion; +- **verify later**: requires an unavailable platform, credential, service, or + long-running qualification environment; +- **needs decision**: requires a compatibility, support, versioning, or policy + choice that would materially change the release contract; +- **not reasonable for this pass**: disproportionate or outside the requested + release scope. + +Never edit the contract merely to convert a failure into a pass. Never suppress +a warning, weaken a test, widen a numerical tolerance, remove platform support, +or relabel an unknown as passing without a technically justified decision. + +Order remediation by dependency. Prefer: + +1. version/scope decisions and build blockers; +2. correctness, compatibility, and real-time defects; +3. build/test/CI coverage needed to prove those fixes; +4. documentation and release metadata; +5. formatting and final hygiene. + +## Flight 2: isolated remediation + +Dispatch independent `fix now` groups to subagents. Use follow-up flights for +work that depends on earlier changes rather than forcing dependent tasks into +parallel execution. + +For every agent that edits files: + +1. Create a uniquely named work branch from the current integration-branch + head and attach it to a private worktree in an explicit temporary path. + Avoid branch names nested beneath the exact integration-branch ref. +2. Tell the agent to work only inside that worktree and only on its assigned + deficiencies. Remind it that other agents are working concurrently. +3. Require focused verification, a coherent commit, the commit SHA, changed + files, commands run, results, and remaining limitations. +4. Instruct the agent not to merge, push, rebase the integration branch, or + modify another worktree. + +The coordinator owns integration. Review each diff and verification result. +Immediately before every merge, assert that the command is running in the +recorded integration worktree, that its symbolic branch is the exact recorded +integration ref, and that the branch is not `main`. Then merge the work branch +in dependency order. Resolve conflicts deliberately; do not discard concurrent +work. After each merge, run the smallest useful cross-check before integrating +dependent work. Remove only skill-created worktrees, without force. Delete a +work branch only after its commit is verified as an ancestor of integration +`HEAD` and its worktree is clean. + +## Final qualification + +After all reasonable fixes are integrated: + +1. Record integration `HEAD`, create a fresh detached final-verification + worktree at that commit, and re-run the complete locally available + qualification suite there. Put build and test outputs in separately recorded + temporary directories outside the worktree wherever possible. Use clean + builds rather than relying only on incremental artifacts. Do not reset or + clean an existing checkout. +2. Re-check formatting, documentation coverage, version consistency, repository + cleanliness, submodule state, and the diff from the frozen `base_sha`. +3. Reconcile every criterion in the ledger with final evidence. +4. Leave unavailable checks as `unknown` and policy choices as unresolved; do + not claim full qualification while either remains material. +5. Confirm no merge was made to `main`, no remote mutation occurred, and the + final-verification worktree has no tracked or untracked changes. Inventory + ignored files and remove only exact, recorded skill-created outputs. Remove + only recorded skill-created worktrees and never force their removal; preserve + and report any worktree containing unexplained files. + +Report: + +- target version, base branch, and integration branch; +- criteria passed, fixed, unknown, not applicable, and still failed; +- commits integrated and the verification performed; +- guarantees the release can substantiate and guarantees it cannot yet make; +- user decisions or external checks still required; and +- the exact next action, while leaving the integration branch ready for review. diff --git a/.agents/skills/release-check/agents/openai.yaml b/.agents/skills/release-check/agents/openai.yaml new file mode 100644 index 00000000..2f47da50 --- /dev/null +++ b/.agents/skills/release-check/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Release Check" + short_description: "Qualify releases with parallel agent flights" + default_prompt: "Use $release-check to qualify version [version] from [base] on development branch [integration branch], then remediate reasonable deficiencies." diff --git a/docs/index.rst b/docs/index.rst index 68c7795b..3f892f28 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,7 @@ Welcome to the NeuralAmpModelerCore documentation. This library provides a core wavenet_walkthrough nam_file_version + release_guarantees api/index Overview @@ -55,6 +56,7 @@ Documentation ------------- * :doc:`wavenet_walkthrough`: Step-by-step explanation of WaveNet architecture, LayerArray, and Layer computations +* :doc:`release_guarantees`: Public quality and compatibility guarantees for covered releases * :doc:`api/index`: Complete API reference Indices and tables diff --git a/docs/release_guarantees.rst b/docs/release_guarantees.rst new file mode 100644 index 00000000..99888dde --- /dev/null +++ b/docs/release_guarantees.rst @@ -0,0 +1,123 @@ +Release guarantees +================== + +.. warning:: + + This policy is a draft. It does not apply retroactively to version 0.5.5 or + any earlier release. The first release covered by this policy will be named + here before the policy takes effect. + +This page describes what users can rely on when choosing a tagged +NeuralAmpModelerCore release. Guarantees apply only to stable releases listed +as covered in the `Version coverage`_ table. They do not apply to development +branches, arbitrary commits, or release candidates unless explicitly stated. + +Guarantees for covered releases +------------------------------- + +Documentation +^^^^^^^^^^^^^ + +* Every public API exposed by the library's headers is included in the API + reference and documented. +* Documentation identifies parameters, return values, errors, ownership and + lifetime requirements, and thread-safety or real-time-safety constraints + where they affect correct use. +* The Doxygen and Sphinx documentation builds complete without errors, broken + references, or undocumented-public-API warnings. +* User documentation is updated when a feature or compatibility change changes + how consumers use the library. + +Build and test quality +^^^^^^^^^^^^^^^^^^^^^^ + +* The exact tagged source passes the project's formatting check. +* Clean Debug and Release builds succeed with the toolchains and platforms + listed for that release. +* The complete unit and integration test suites pass on the exact tagged + source. +* Supported build variants, including optional optimized implementations, are + tested in both their enabled and disabled configurations where applicable. +* At least one supported downstream consumer is built against the release + candidate before the stable release is tagged. + +Model compatibility and correctness +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* The release loads and processes every ``.nam`` file version identified as + supported in :doc:`nam_file_version`. +* Representative models for every supported architecture are loaded and + rendered as part of release qualification. +* Optimized and generic processing paths are checked for equivalent output + within documented numerical tolerances. +* Reference audio comparisons protect against unintended changes to rendered + output. +* Intentional compatibility or output changes that require consumer action are + identified in the relevant user or API documentation. + +Real-time behavior +^^^^^^^^^^^^^^^^^^ + +* Processing APIs documented as real-time safe perform no dynamic allocation + after required initialization and prewarming have completed. +* Real-time-safety tests cover every supported model architecture for which the + guarantee is made. +* Any operation that can allocate, lock, perform file access, or otherwise be + unsuitable for an audio thread is identified in its API documentation. + +Performance +^^^^^^^^^^^ + +* Release-candidate benchmarks are compared with the preceding stable release + using a recorded test environment. +* Material regressions in processing speed, memory use, or initialization time + are either resolved before release or explicitly accepted during release + qualification. +* A performance optimization does not relax correctness or real-time-safety + requirements unless the exception is explicitly documented. + +Dependencies and source integrity +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Dependency and submodule revisions are pinned, publicly retrievable, and + sufficient for a recursive clean checkout to build without untracked local + files. +* The release tag identifies the exact source revision that passed release + qualification. +* Applicable dependency licenses and attributions are retained in the source + distribution. + +Limits of the guarantees +------------------------ + +Unless a particular release says otherwise, these guarantees do not promise: + +* ABI compatibility between releases; +* bit-identical floating-point output across different processors or + toolchains; +* support for platforms, toolchains, architectures, or build configurations + not listed for that release; or +* stability of undocumented implementation details. + +Version coverage +---------------- + +.. list-table:: Release guarantee coverage + :header-rows: 1 + :widths: 20 25 55 + + * - Core release + - Policy status + - Notes + * - 0.5.5 and earlier + - Not covered + - These releases predate this policy and receive no retroactive guarantee + under it. + * - To be determined + - Draft + - The first covered release will be recorded here when the policy is + adopted. + +For each covered release, this table will also identify the tested platforms, +toolchains, processor architectures, build variants, and any explicitly +documented exceptions. diff --git a/example_models/wavenet_a2_max.nam b/example_models/wavenet_a2_feature_test.nam similarity index 99% rename from example_models/wavenet_a2_max.nam rename to example_models/wavenet_a2_feature_test.nam index 6ee3b0f7..c1cf26dd 100644 --- a/example_models/wavenet_a2_max.nam +++ b/example_models/wavenet_a2_feature_test.nam @@ -1,6 +1,6 @@ { "notes": [ - "This model is meant as a 'test case' to contain all of the new features that are being considered for A2.", + "This model is meant as a test case containing all proposed A2 features; it is not the A2-Full architecture.", "It doesn't have slimmability." ], "version": "0.6.0", @@ -2163,4 +2163,4 @@ -0.9127054018053962 ], "sample_rate": 48000 -} \ No newline at end of file +} diff --git a/generate_weights_a2.py b/generate_weights_a2.py index bf091c43..af96e239 100644 --- a/generate_weights_a2.py +++ b/generate_weights_a2.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Generate weights for wavenet_a2_max.nam file. +Generate weights for the wavenet_a2_feature_test.nam file. This script handles the full A2 architecture including: - FiLM (Feature-wise Linear Modulation) modules - head1x1 modules @@ -329,14 +329,14 @@ def main(): parser.add_argument( "--input", type=Path, - default=Path("example_models/wavenet_a2_max.nam"), - help="Input .nam file with empty weights (default: example_models/wavenet_a2_max.nam)" + default=Path("example_models/wavenet_a2_feature_test.nam"), + help="Input .nam feature-test file with empty weights (default: example_models/wavenet_a2_feature_test.nam)" ) parser.add_argument( "--output", type=Path, - default=Path("example_models/wavenet_a2_max_withweights.nam"), - help="Output .nam file (default: example_models/wavenet_a2_max_withweights.nam)" + default=Path("example_models/wavenet_a2_feature_test_withweights.nam"), + help="Output .nam file (default: example_models/wavenet_a2_feature_test_withweights.nam)" ) parser.add_argument( "--seed", diff --git a/tools/test/test_container.cpp b/tools/test/test_container.cpp index b4dc65c8..c12cdb96 100644 --- a/tools/test/test_container.cpp +++ b/tools/test/test_container.cpp @@ -140,24 +140,24 @@ void process_and_verify(nam::DSP* dsp, int num_buffers, int buffer_size) void test_container_loads_from_json() { - auto j = - build_container_json("example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_max.nam"); + auto j = build_container_json( + "example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_feature_test.nam"); auto dsp = nam::get_dsp(j); assert(dsp != nullptr); } void test_container_processes_audio() { - auto j = - build_container_json("example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_max.nam"); + auto j = build_container_json( + "example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_feature_test.nam"); auto dsp = nam::get_dsp(j); process_and_verify(dsp.get(), 3, 64); } void test_container_slimmable_selects_submodel() { - auto j = - build_container_json("example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_max.nam"); + auto j = build_container_json( + "example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_feature_test.nam"); auto dsp = nam::get_dsp(j); const double sample_rate = 48000.0; const int buffer_size = 64; @@ -198,8 +198,8 @@ void test_container_slimmable_selects_submodel() void test_container_boundary_values() { - auto j = - build_container_json("example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_max.nam"); + auto j = build_container_json( + "example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_feature_test.nam"); auto dsp = nam::get_dsp(j); const double sample_rate = 48000.0; const int buffer_size = 16; @@ -380,8 +380,8 @@ void test_container_load_from_file() void test_container_default_is_max_size() { - auto j = - build_container_json("example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_max.nam"); + auto j = build_container_json( + "example_models/lstm.nam", "example_models/wavenet.nam", "example_models/wavenet_a2_feature_test.nam"); auto dsp = nam::get_dsp(j); const double sample_rate = 48000.0; const int buffer_size = 64; diff --git a/tools/test/test_get_dsp.cpp b/tools/test/test_get_dsp.cpp index de20ce84..538f70c0 100644 --- a/tools/test/test_get_dsp.cpp +++ b/tools/test/test_get_dsp.cpp @@ -242,7 +242,7 @@ void test_load_and_process_nam_files() // Paths are relative to root directory where tests run (./build/tools/run_tests) const std::vector nam_files = {"example_models/wavenet.nam", "example_models/lstm.nam", "example_models/wavenet_condition_dsp.nam", - "example_models/wavenet_a2_max.nam"}; + "example_models/wavenet_a2_feature_test.nam"}; const int num_buffers = 3; const int buffer_size = 64; From ce1e723c85dcb8d2073b6ef39ca1961310709b37 Mon Sep 17 00:00:00 2001 From: Steven Atkinson Date: Sat, 22 Aug 2026 22:48:33 -0700 Subject: [PATCH 2/3] Keep local agent configuration untracked --- .agents/skills/release-check/SKILL.md | 206 ------------------ .../skills/release-check/agents/openai.yaml | 4 - 2 files changed, 210 deletions(-) delete mode 100644 .agents/skills/release-check/SKILL.md delete mode 100644 .agents/skills/release-check/agents/openai.yaml diff --git a/.agents/skills/release-check/SKILL.md b/.agents/skills/release-check/SKILL.md deleted file mode 100644 index b20414f2..00000000 --- a/.agents/skills/release-check/SKILL.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -name: release-check -description: "Assess a repository against a release checklist or public release-guarantees document, and when fixes are explicitly requested, remediate deficiencies using two coordinated flights of subagents: evidence gathering, then isolated-worktree fixes merged into a user-named development integration branch. Use when asked to qualify, prepare, harden, audit, or make a codebase ready for a release without publishing the release." ---- - -# Release Check - -Qualify a release with evidence, then repair reasonable deficiencies when the -request authorizes fixes, without weakening the release contract. Keep all work -on the user-named development integration branch. This workflow must never -merge to a branch literally named `main`. - -## Establish scope and branch roles - -1. Read repository instructions and inspect status, remotes, branches, - worktrees, version sources, tags, and CI configuration. Do not alter the - user's original checkout. -2. Find the governing criteria in this order: - - a path or checklist supplied by the user; - - `docs/release_guarantees.rst`; - - `RELEASE_GUARANTEES.md`, `RELEASING.md`, or equivalent project docs; - - a checklist explicitly derived with the user when no contract exists. -3. Determine whether the request is assessment-only or explicitly authorizes - remediation. Assessment-only requests must not create branches or commits. -4. Determine and record `target_version`, the base ref, immutable `base_sha`, - and, for remediation, the requested integration ref. Distinguish these - branch roles: - - **base branch**: the branch from which qualification starts; - - **integration branch**: the user-named development branch that receives - all qualification fixes, such as `release-check`; - - **work branches**: short-lived branches in private worktrees used by - remediation agents. -5. Resolve identity from the request and repository evidence. Ask if the target - version, base, or integration branch remains ambiguous. Reject `main` as the - integration target rather than silently substituting another branch. -6. If the intended release includes uncommitted changes, stop and ask for an - immutable committed revision or explicit exclusion of those changes. Do not - silently omit or capture them. -7. Define `qualification_start_sha`, the immutable commit Flight 1 assesses. - For a new integration branch it equals `base_sha`; for an existing - integration branch it is that branch's current `HEAD`; for assessment-only - work it is the commit selected by the user or current repository context. -8. Preserve all pre-existing user changes. Do not stash, discard, commit, move, - reset, or clean them. -9. Treat a draft guarantee policy as candidate criteria only. If it excludes - the target version, do not change its coverage or claim the version is - guaranteed without explicit user authorization. - -## Plan the qualification - -Create a plan with separate assessment, remediation, integration, and final -verification stages. Convert the governing document into atomic criteria with -stable identifiers. Include applicable criteria for: - -- versioning, release scope, and deprecations; -- formatting, compiler warnings, and source hygiene; -- public API and user documentation; -- clean Debug and Release builds, supported build variants, and tests; -- supported platforms, toolchains, architectures, and downstream consumers; -- model/file compatibility and DSP output correctness; -- real-time safety and thread behavior; -- performance and memory regressions; -- dependencies, licenses, and source reproducibility; and -- tag, artifact, and publication readiness. - -Do not create or fail a criterion because a changelog or release-notes file is -absent from the repository. This project uses GitHub-generated release notes; -their generation and publication happen outside the pre-release repository -qualification unless the user explicitly requests a hosted-release check. - -Do not push, tag, create a pull request or hosted release, dispatch remote -workflows, upload packages or artifacts, deploy, sign or notarize artifacts, or -update downstream repositories unless the user separately authorizes those -external changes. - -## Flight 1: independent assessment - -Use subagents for a repository-read-only first flight. Before dispatch, create -one disposable detached worktree per assessor at `qualification_start_sha`. -Place build and test outputs in separately recorded temporary directories -outside the worktree wherever the tools allow it. Forbid tracked changes, -commits, branch/ref changes, and remote mutations. Partition criteria into -bounded, non-overlapping groups and adapt the number of groups to the available -concurrency. A useful partition is: - -1. API documentation, user docs, versioning, and release metadata. -2. builds, CI, unit/integration tests, sanitizers, and consumer compatibility. -3. model compatibility, DSP correctness, real-time safety, and performance. -4. dependencies, licensing, reproducibility, and publishing readiness. - -Give each agent its worktree path, target version, frozen qualification identity, -criteria IDs, and integration branch. Require this result for every criterion: - -- status: `pass`, `fail`, `unknown`, or `not-applicable`; -- concise evidence with file paths, line numbers, commands, or test output; -- the exact deficiency when status is not `pass`; -- a proposed remediation and its validation command; -- dependencies, risk, and whether the environment can verify it. - -Require each assessor to finish with `git status --porcelain` evidence and no -tracked or untracked changes. Before cleanup, inventory ignored files and -delete only explicitly recorded outputs created by the skill after resolving -their exact paths. Never use a broad clean command. Remove only the recorded -disposable worktrees, without force, after findings and outputs are captured. -If unexplained files remain, preserve the worktree and report it. - -Require execution evidence where practical. The existence of a test, workflow, -or documentation setting is not proof that it passes. An unavailable platform -or service is `unknown`, not `pass`. - -## Consolidate and decide - -Wait for all assessment agents, resolve contradictory findings against primary -evidence, and create one qualification ledger containing every criterion. -Summarize the ledger for the user before remediation. For audit, assess, review, -or qualify-only requests, stop here. Continue into remediation only when the -user explicitly asked to fix, prepare, harden, or make the release ready. - -Before remediation, inspect the worktree list. Create a dedicated integration -worktree at an explicit recorded path: create a new integration branch at -`base_sha`, or attach the existing integration branch at -`qualification_start_sha` without overwriting it. If that ref is already -checked out in a user-owned worktree, do not modify or detach it; ask the user -to release it or explicitly authorize use of that exact worktree. Perform every -coordinator branch, commit, and merge operation inside the recorded integration -worktree, never the original checkout. - -Classify failed and unknown criteria as: - -- **fix now**: bounded repository work directly needed to meet the criterion; -- **verify later**: requires an unavailable platform, credential, service, or - long-running qualification environment; -- **needs decision**: requires a compatibility, support, versioning, or policy - choice that would materially change the release contract; -- **not reasonable for this pass**: disproportionate or outside the requested - release scope. - -Never edit the contract merely to convert a failure into a pass. Never suppress -a warning, weaken a test, widen a numerical tolerance, remove platform support, -or relabel an unknown as passing without a technically justified decision. - -Order remediation by dependency. Prefer: - -1. version/scope decisions and build blockers; -2. correctness, compatibility, and real-time defects; -3. build/test/CI coverage needed to prove those fixes; -4. documentation and release metadata; -5. formatting and final hygiene. - -## Flight 2: isolated remediation - -Dispatch independent `fix now` groups to subagents. Use follow-up flights for -work that depends on earlier changes rather than forcing dependent tasks into -parallel execution. - -For every agent that edits files: - -1. Create a uniquely named work branch from the current integration-branch - head and attach it to a private worktree in an explicit temporary path. - Avoid branch names nested beneath the exact integration-branch ref. -2. Tell the agent to work only inside that worktree and only on its assigned - deficiencies. Remind it that other agents are working concurrently. -3. Require focused verification, a coherent commit, the commit SHA, changed - files, commands run, results, and remaining limitations. -4. Instruct the agent not to merge, push, rebase the integration branch, or - modify another worktree. - -The coordinator owns integration. Review each diff and verification result. -Immediately before every merge, assert that the command is running in the -recorded integration worktree, that its symbolic branch is the exact recorded -integration ref, and that the branch is not `main`. Then merge the work branch -in dependency order. Resolve conflicts deliberately; do not discard concurrent -work. After each merge, run the smallest useful cross-check before integrating -dependent work. Remove only skill-created worktrees, without force. Delete a -work branch only after its commit is verified as an ancestor of integration -`HEAD` and its worktree is clean. - -## Final qualification - -After all reasonable fixes are integrated: - -1. Record integration `HEAD`, create a fresh detached final-verification - worktree at that commit, and re-run the complete locally available - qualification suite there. Put build and test outputs in separately recorded - temporary directories outside the worktree wherever possible. Use clean - builds rather than relying only on incremental artifacts. Do not reset or - clean an existing checkout. -2. Re-check formatting, documentation coverage, version consistency, repository - cleanliness, submodule state, and the diff from the frozen `base_sha`. -3. Reconcile every criterion in the ledger with final evidence. -4. Leave unavailable checks as `unknown` and policy choices as unresolved; do - not claim full qualification while either remains material. -5. Confirm no merge was made to `main`, no remote mutation occurred, and the - final-verification worktree has no tracked or untracked changes. Inventory - ignored files and remove only exact, recorded skill-created outputs. Remove - only recorded skill-created worktrees and never force their removal; preserve - and report any worktree containing unexplained files. - -Report: - -- target version, base branch, and integration branch; -- criteria passed, fixed, unknown, not applicable, and still failed; -- commits integrated and the verification performed; -- guarantees the release can substantiate and guarantees it cannot yet make; -- user decisions or external checks still required; and -- the exact next action, while leaving the integration branch ready for review. diff --git a/.agents/skills/release-check/agents/openai.yaml b/.agents/skills/release-check/agents/openai.yaml deleted file mode 100644 index 2f47da50..00000000 --- a/.agents/skills/release-check/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Release Check" - short_description: "Qualify releases with parallel agent flights" - default_prompt: "Use $release-check to qualify version [version] from [base] on development branch [integration branch], then remediate reasonable deficiencies." From d4f44eed2cd5366f70fce6273ae52c74abaf7cef Mon Sep 17 00:00:00 2001 From: Steven Atkinson Date: Sat, 22 Aug 2026 22:50:20 -0700 Subject: [PATCH 3/3] Limit PR to A2 fixture clarification --- docs/index.rst | 2 - docs/release_guarantees.rst | 123 ------------------------------------ 2 files changed, 125 deletions(-) delete mode 100644 docs/release_guarantees.rst diff --git a/docs/index.rst b/docs/index.rst index 3f892f28..68c7795b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,6 @@ Welcome to the NeuralAmpModelerCore documentation. This library provides a core wavenet_walkthrough nam_file_version - release_guarantees api/index Overview @@ -56,7 +55,6 @@ Documentation ------------- * :doc:`wavenet_walkthrough`: Step-by-step explanation of WaveNet architecture, LayerArray, and Layer computations -* :doc:`release_guarantees`: Public quality and compatibility guarantees for covered releases * :doc:`api/index`: Complete API reference Indices and tables diff --git a/docs/release_guarantees.rst b/docs/release_guarantees.rst deleted file mode 100644 index 99888dde..00000000 --- a/docs/release_guarantees.rst +++ /dev/null @@ -1,123 +0,0 @@ -Release guarantees -================== - -.. warning:: - - This policy is a draft. It does not apply retroactively to version 0.5.5 or - any earlier release. The first release covered by this policy will be named - here before the policy takes effect. - -This page describes what users can rely on when choosing a tagged -NeuralAmpModelerCore release. Guarantees apply only to stable releases listed -as covered in the `Version coverage`_ table. They do not apply to development -branches, arbitrary commits, or release candidates unless explicitly stated. - -Guarantees for covered releases -------------------------------- - -Documentation -^^^^^^^^^^^^^ - -* Every public API exposed by the library's headers is included in the API - reference and documented. -* Documentation identifies parameters, return values, errors, ownership and - lifetime requirements, and thread-safety or real-time-safety constraints - where they affect correct use. -* The Doxygen and Sphinx documentation builds complete without errors, broken - references, or undocumented-public-API warnings. -* User documentation is updated when a feature or compatibility change changes - how consumers use the library. - -Build and test quality -^^^^^^^^^^^^^^^^^^^^^^ - -* The exact tagged source passes the project's formatting check. -* Clean Debug and Release builds succeed with the toolchains and platforms - listed for that release. -* The complete unit and integration test suites pass on the exact tagged - source. -* Supported build variants, including optional optimized implementations, are - tested in both their enabled and disabled configurations where applicable. -* At least one supported downstream consumer is built against the release - candidate before the stable release is tagged. - -Model compatibility and correctness -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* The release loads and processes every ``.nam`` file version identified as - supported in :doc:`nam_file_version`. -* Representative models for every supported architecture are loaded and - rendered as part of release qualification. -* Optimized and generic processing paths are checked for equivalent output - within documented numerical tolerances. -* Reference audio comparisons protect against unintended changes to rendered - output. -* Intentional compatibility or output changes that require consumer action are - identified in the relevant user or API documentation. - -Real-time behavior -^^^^^^^^^^^^^^^^^^ - -* Processing APIs documented as real-time safe perform no dynamic allocation - after required initialization and prewarming have completed. -* Real-time-safety tests cover every supported model architecture for which the - guarantee is made. -* Any operation that can allocate, lock, perform file access, or otherwise be - unsuitable for an audio thread is identified in its API documentation. - -Performance -^^^^^^^^^^^ - -* Release-candidate benchmarks are compared with the preceding stable release - using a recorded test environment. -* Material regressions in processing speed, memory use, or initialization time - are either resolved before release or explicitly accepted during release - qualification. -* A performance optimization does not relax correctness or real-time-safety - requirements unless the exception is explicitly documented. - -Dependencies and source integrity -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* Dependency and submodule revisions are pinned, publicly retrievable, and - sufficient for a recursive clean checkout to build without untracked local - files. -* The release tag identifies the exact source revision that passed release - qualification. -* Applicable dependency licenses and attributions are retained in the source - distribution. - -Limits of the guarantees ------------------------- - -Unless a particular release says otherwise, these guarantees do not promise: - -* ABI compatibility between releases; -* bit-identical floating-point output across different processors or - toolchains; -* support for platforms, toolchains, architectures, or build configurations - not listed for that release; or -* stability of undocumented implementation details. - -Version coverage ----------------- - -.. list-table:: Release guarantee coverage - :header-rows: 1 - :widths: 20 25 55 - - * - Core release - - Policy status - - Notes - * - 0.5.5 and earlier - - Not covered - - These releases predate this policy and receive no retroactive guarantee - under it. - * - To be determined - - Draft - - The first covered release will be recorded here when the policy is - adopted. - -For each covered release, this table will also identify the tested platforms, -toolchains, processor architectures, build variants, and any explicitly -documented exceptions.