diff options
| author | Andre Bezerra <amelco.herman@gmail.com> | 2026-11-17 11:19:16 -0300 |
|---|---|---|
| committer | Andre Bezerra <amelco.herman@gmail.com> | 2026-11-17 11:59:21 -0300 |
| commit | c63dcf6248d9d6dad5c78e91a434e2b8409e3f3c (patch) | |
| tree | d3b93d1878e41906ed65d08ccc6cf5b20c911cf8 | |
| parent | 4a9b361b62a90b4f9cd2f7fb64471c5e3d3c8c4f (diff) | |
add the agent harness
Add AGENTS.md with the project's non-negotiables and pipeline, the skills
that implement each stage, the mechanical check script, and the ADR and
report templates the pipeline requires.
| -rw-r--r-- | .agents/skills/architect.md | 104 | ||||
| -rw-r--r-- | .agents/skills/coder.md | 69 | ||||
| -rw-r--r-- | .agents/skills/reviewer.md | 64 | ||||
| -rw-r--r-- | .agents/skills/spec.md | 93 | ||||
| -rw-r--r-- | .agents/skills/style.md | 126 | ||||
| -rw-r--r-- | .agents/skills/tester.md | 92 | ||||
| -rw-r--r-- | AGENTS.md | 113 | ||||
| -rw-r--r-- | docs/adr/0000-template.md | 21 | ||||
| -rw-r--r-- | docs/reports/0000-template.md | 43 | ||||
| -rwxr-xr-x | scripts/check.sh | 95 |
10 files changed, 820 insertions, 0 deletions
diff --git a/.agents/skills/architect.md b/.agents/skills/architect.md new file mode 100644 index 0000000..193d2c7 --- /dev/null +++ b/.agents/skills/architect.md @@ -0,0 +1,104 @@ +--- +name: architect +description: Use when a change adds or moves a module, header, directory, public function, CLI flag, output format, or dependency — any change that alters the shape of the code rather than only its internals. +whenToUse: After spec, before coder, for normal and architectural tier changes. +--- + +# architect + +Decides where code goes and how modules may depend on each other. It does not +write code and does not restate style. + +This file describes the architecture the project **is converging to**, and names +the places where the code has not arrived yet. When the code and this file +disagree, one of them is a bug — fix one of them in the same change. + +## Triggers + +- New module, new directory, new submodule. +- A function in `main.c` is growing, or `main.c` gains a new responsibility. +- New dependency, new runtime tool, new external process. +- A change to the CLI surface, the output file contract, or the on-disk layout. + +## The one rule that matters + +**`main.c` orchestrates. Modules do the work.** + +`main.c` parses arguments, decides which mode runs, and drives the pipeline by +calling modules. It does not implement business logic: no parsing internals, no +DSP, no file-format handling, no model plumbing. + +## Module shape + +- One pair of `.c`/`.h` files per module. +- A module owns one responsibility and exposes it through its header. +- Internal helpers are `static` and never appear in the header. +- A shared internal header (e.g. `audio_internal.h`) is allowed between modules + that implement the same interface, and nowhere else. + +## Indirection budget + +Do not stack layers. A module calling another module is allowed only when the +logic genuinely does not belong where it is — never to create an abstraction +because it looks tidier. + +Test before adding a layer: *can I name the piece of logic that has no home?* +If the answer is vague, the new layer is not justified. + +## Current module map + +<!-- Mutable. Update in the same change that alters it. --> + +| File | Owns | +| --- | --- | +| `main.c` | CLI parsing, mode dispatch, pipeline orchestration, output publication, signals | +| `audio.c` / `audio.h` | Input dispatch: picks the reader and exposes one interface | +| `audio_wav.c` | RIFF/WAVE parsing, PCM and float decoding, resampling source | +| `audio_mp3.c` | MPEG Layer III decoding via dr_mp3, tag handling, gapless trimming | +| `audio_internal.h`, `bytes.h` | Shared internals for the audio modules | +| `playback.c` / `playback.h` | Stem playback through `mpv`, input config, status filtering | +| `metronome.c` / `metronome.h` | Bar synthesis and metronome playback | + +**Known debt.** `main.c` still holds logic that belongs to modules: the +resampler, the WAV writer, the overlap-add stitching, and the ONNX binding. The +target is one module per concern. New work must not add more of this; when a +change touches one of those areas, consider extracting it first and say so. + +## Dependencies + +The default is **zero dependencies** — everything done in house. + +- A new dependency is acceptable when it is the only reasonable way to ship the + feature. It requires: + 1. an ADR in `docs/adr/` recording why it was chosen, + 2. a follow-up task to remove it again. +- `mpv` is the current accepted exception: it is a player, and building a player + is not this project. It is expected to be replaced eventually by a minimal + in-house player. +- When a dependency is removed, implement **only the features this program + actually uses**. Not the full surface of the dependency. + +## Contracts + +- Errors are reported to the caller; a module never exits the process. +- Ownership is explicit at every boundary: who allocates, who frees. +- The CLI surface and the output file contract are public API. Changing either + is architectural and requires the README to change in the same commit. + +## ADRs + +`docs/adr/NNNN-title.md`, one file per non-obvious decision, using +`docs/adr/0000-template.md`. Write one when: + +- a dependency is added, removed, or replaced; +- a module is created, split, or merged; +- a public contract changes; +- a design was chosen over a plausible alternative worth remembering. + +## Design checklist + +- [ ] Does the change fit an existing module? +- [ ] If a new module: is the responsibility nameable in one sentence? +- [ ] Does it add indirection that the code does not need? +- [ ] Does it add a dependency, and is the ADR plus removal task recorded? +- [ ] Does it change an observable contract, and is the documentation updated? diff --git a/.agents/skills/coder.md b/.agents/skills/coder.md new file mode 100644 index 0000000..7bc43d0 --- /dev/null +++ b/.agents/skills/coder.md @@ -0,0 +1,69 @@ +--- +name: coder +description: Use when implementing an approved spec or bug fix in source code — the edit-build-verify loop, the commit, and the written report. Do not use before a spec exists. +whenToUse: After spec, and after architect when the change is structural. +--- + +# coder + +Implements exactly the SPEC. Smallest correct diff, no drive-by changes, and +evidence for every claim. + +## Preconditions + +- [ ] A SPEC exists with acceptance criteria. +- [ ] `architect` has ruled, for structural changes. +- [ ] The build is clean **before** the first edit. If it is not, stop and report. + +## The loop + +1. Read the code you are about to change. Never edit blind. +2. State the plan in one short paragraph, then execute it. +3. Make the smallest change that satisfies one acceptance criterion. +4. Build after every meaningful edit. +5. Run the tests that cover the touched surface. +6. Re-read your own diff before handing it to review. + +## Change discipline + +- No reformatting of lines you did not otherwise need to touch. +- No renaming or refactoring the SPEC did not require. +- No new dependency without an ADR and a removal task (see `architect`). +- Match the surrounding code, not personal preference. +- **Adjacent fixes are allowed and expected**: an obviously wrong line next to + your change (a leak, a wrong check, a stale error message) gets fixed. Record + it in the report. A refactor is not an adjacent fix. + +## Error and resource handling + +Follow the conventions in `style`. In particular: every new failure path is +handled and reported; nothing is silently ignored; every allocation has an +owner and a matching free on every exit path, including error paths. + +## Commit + +- Exactly **one commit per task**, made by the coder at the end. +- The human does not review the commit — `reviewer` does, and review happens + **before** the commit. +- The commit message states what changed and why, in the imperative mood. +- Commit only source, docs, tests, and reports. Never build outputs, binaries, + media, or model weights. + +## Report + +Every task leaves `docs/reports/NNNN-<slug>.md` in the repo, following +`docs/reports/0000-template.md`. + +## Hard stops + +- The SPEC is missing or a blocking question is open. +- A non-negotiable would have to be broken. +- The build was already broken before the edit. +- The change turns out to require a design decision the SPEC did not cover. + +## Anti-patterns + +- "While I was here" refactoring. +- Declaring success from a clean compile alone. +- Touching the test to make it pass instead of touching the code. +- Adding an abstraction because the diff felt too direct. diff --git a/.agents/skills/reviewer.md b/.agents/skills/reviewer.md new file mode 100644 index 0000000..887f653 --- /dev/null +++ b/.agents/skills/reviewer.md @@ -0,0 +1,64 @@ +--- +name: reviewer +description: Use after implementation and before the commit, to review a diff against the SPEC and the non-negotiables. Only valid when the reviewer did not write the code. +whenToUse: End of every normal and architectural tier change, in fresh context. +--- + +# reviewer + +Adversarial, independent, evidence-based. An implementer reviewing its own work +is confirmation, not review. This skill exists because the author and the judge +must be different contexts. + +## Preconditions + +- [ ] The reviewer did not write this code. +- [ ] The SPEC and the full diff are available. +- [ ] The build and test commands can be re-run by the reviewer. + +## Order of review + +1. **Spec conformance** — is this the right target? (cheapest place to catch a + wasted change) +2. **Non-negotiables** — R1–R7, citing the rule id. +3. **Correctness** — edge cases, error paths, resource leaks, integer overflow. +4. **Regression surface** — what the change can break next to it. +5. **Style** — last, and only as a minor finding. + +## Severity + +| Level | Meaning | Effect | +| --- | --- | --- | +| Blocker | Correctness defect, data loss, broken build, or a non-negotiable violated | Blocks the commit | +| Major | An acceptance criterion is unmet, or the change is incomplete | Blocks the commit | +| Minor | Style inconsistency, naming, unclear message | Reported, does not block | +| Nit | Preference | Never blocks; may be ignored | + +The reviewer **can block**. A blocked change returns to the coder. + +## Verdict + +```text +REVIEW +- Verdict: pass | pass-with-findings | fail +- Findings: + - [severity] [rule id or file:line] problem -> required change +- Re-ran: <command> -> <result> +``` + +## Rules of the reviewer + +- Every finding names a concrete consequence. "This is ugly" is not a finding. +- No finding without reading the code it refers to. +- The reviewer re-runs the build and the tests. "Should work" is not a verdict. +- The reviewer proposes; the implementer edits. Never rewrite the diff yourself. +- Style is advisory; correctness and data safety are not. +- If the change looks right but the SPEC is wrong, say so — that is the most + valuable finding this skill can produce. + +## Anti-patterns + +- Approving without running anything. +- Findings that are preferences dressed as defects. +- Restating the diff instead of judging it. +- Rubber-stamping because the change is small. diff --git a/.agents/skills/spec.md b/.agents/skills/spec.md new file mode 100644 index 0000000..5303b34 --- /dev/null +++ b/.agents/skills/spec.md @@ -0,0 +1,93 @@ +--- +name: spec +description: Use when a feature request, bug report, or change request arrives and must be turned into explicit, testable acceptance criteria before any code is written. Also use when requirements are ambiguous, contradictory, or unmeasurable. +whenToUse: At the start of every non-trivial task, before architect or coder. +--- + +# spec + +Turns a request into a contract. The output is what every later stage is judged +against, so it must be observable and testable. + +This skill **does not design**. It does not pick modules, algorithms, or +libraries. It answers one question: *how will we know this is done?* + +## Triggers + +- A request arrives and the expected observable behaviour is not obvious. +- The request uses words like "better", "faster", "should work", "fix", "sounds wrong". +- The request contradicts the README, an existing test, or current behaviour. +- The request has more than one reasonable interpretation. + +## Inputs + +- The raw request, verbatim. +- `README.md` — the documented contract. +- The current behaviour, where it can be observed cheaply. + +## Procedure + +1. **Restate the request in one sentence**, without adding requirements. +2. **List acceptance criteria** as observable facts: something a command can + print, a file can contain, or an exit code can report. +3. **Split** into *must*, *should*, and *out of scope*. Out-of-scope items are + mandatory: they are what stops the work from growing. +4. **Convert unmeasurable criteria.** Any criterion that cannot be failed by a + concrete observation is rewritten as a proxy that can. State the proxy and + its threshold explicitly. +5. **Classify ambiguities:** + - *internal and reversible* → decide it, record the decision and the reason; + - *observable, irreversible, or contradicting documentation* → **stop and ask**. +6. **List the surfaces touched:** CLI, output files, on-disk layout, docs, tests. +7. **List what could regress** — the neighbouring behaviour most likely to break. +8. **Assign a tier** using the table in `AGENTS.md`. + +## Converting unmeasurable requirements + +The rewrite must keep the intent and gain a threshold. + +| Unmeasurable | Proxy that can fail | +| --- | --- | +| "the separation sounds better" | bleed measured on a known reference stem, or a stated null test | +| "it should be faster" | wall-clock threshold for a fixed input on this machine | +| "the output should be cleaner" | peak amplitude, DC offset, or NaN/Inf count | +| "the code should be simpler" | a named structural property, e.g. "the module has no new dependency" | + +If no honest proxy exists, say so. Do not invent a metric that measures nothing. + +## Output + +```text +SPEC +- Request (restated): +- Tier: trivial | normal | architectural +- Acceptance criteria: + 1. <observable fact> -> evidence: <command or observation> +- Out of scope: +- Decisions taken (internal, reversible): +- Open questions (blocking, observable): +- Surfaces touched: +- Regression risks: +``` + +## Exit criteria + +- Every acceptance criterion can be failed by a concrete command or observation. +- No acceptance criterion contains an unmeasurable adjective. +- Out-of-scope is non-empty for anything larger than a one-file fix. +- Either there are no blocking questions, or the task stops here. + +## Blocked + +When a blocking ambiguity exists: state the question, state the options and the +consequence of each, and stop before writing code. Do not implement a guess and +ask afterwards — a guess that touches an observable contract is the expensive +kind of mistake. + +## Anti-patterns + +- Inventing requirements the request did not contain. +- Turning a one-line bug fix into a design document. A three-line SPEC is still + a SPEC when the change is genuinely small. +- Writing acceptance criteria that restate the implementation ("add a function + that...") instead of the behaviour. diff --git a/.agents/skills/style.md b/.agents/skills/style.md new file mode 100644 index 0000000..342f87c --- /dev/null +++ b/.agents/skills/style.md @@ -0,0 +1,126 @@ +--- +name: style +description: Use whenever C code is written, read, or reviewed in this repo — the concrete naming, formatting, and idiom conventions a diff must follow. +whenToUse: During implementation and during review, alongside coder and reviewer. +--- + +# style + +Conventions, not taste. Every rule below was derived from the code as it exists +today. A rule that the codebase does not already follow does not belong here. + +Style violations are **reported, not blocking** (see `reviewer`). They are still +expected to be fixed before the commit when the fix is local. + +## Formatting + +- One indentation level is **4 spaces**. Never a tab character. +- Lines stay within **100 columns**; only two lines in the whole codebase exceed it. +- An opening brace for a **function definition goes on its own line**. +- An opening brace for `if`, `for`, `while`, `do`, `else` **stays on the same line**: + ```c + static bool checked_add_u64(uint64_t left, uint64_t right, uint64_t *result) + { + if (UINT64_MAX - left < right) { + return false; + } + *result = left + right; + return true; + } + ``` +- `} else {` and `} else if (...) {` on one line. +- **Braces are always used**, including single-statement bodies. +- One statement per line. +- A blank line between functions; none between a function's opening brace and + its first statement. + +## Naming + +- **Variables and functions:** lowercase words. The separator is `_` + (`audio_source_open`, `checked_mul_u64`, `g_interrupted`). + *Note: this is recorded as `snake_case`. Hyphens are not legal in C + identifiers, so the "kebab-case" rule also resolves to the underscore form, + which is what the entire codebase already uses.* +- **Structs, enums, typedefs:** `PascalCase` — `WavWriter`, `AudioSource`, + `ModelResult`, `SampleFormat`. +- **Macros and constants:** `SCREAMING_SNAKE_CASE` — `WAV_WRITE_BLOCK_FRAMES`, + `MODEL_SEGMENT_FRAMES`. +- **Enum constants:** `SCREAMING_SNAKE_CASE` — `EXIT_INPUT`, `EXIT_USAGE`. +- **File-scope mutable state:** `g_` prefix — `g_interrupted`. +- Everything not in a module's header is `static`. + +## Types and literals + +- Use fixed-width integers from `<stdint.h>` at binary and file boundaries. +- Unsigned literals carry a suffix: `0U`, `UINT64_C(343980)`, `1.0e-8F` for floats. +- Define anonymous structs through a typedef: + ```c + typedef struct { + char message[768]; + } Error; + ``` +- Hide implementations behind opaque handles where the struct is private: + `typedef struct AudioSource AudioSource;`. +- Platform assumptions are asserted, not assumed: + `_Static_assert(CHAR_BIT == 8, "...");`. +- Cast deliberately-unused parameters: `(void)signal_number;`. + +## Includes and headers + +1. `#define` feature macros first (`_POSIX_C_SOURCE`, `_FILE_OFFSET_BITS`), + before any `#include`. +2. System headers in one block, `<angle brackets>`, alphabetical. +3. A blank line, then local headers in `"quotes"`, alphabetical. +4. Header guards are `STEMSEP_<NAME>_H`. +5. A header declares only the module's public surface. Shared internals go in an + internal header (`audio_internal.h`) used only by the modules that implement + the same interface. + +## Functions + +- A function does one thing and its name says which. +- Return `bool` for success and report the reason through an out-parameter — + never `exit()`, never print from inside a module. +- Prefer an explicit check over a clever expression; the codebase is written to + be read by someone debugging at 2 a.m. + +## Errors + +- Two out-parameter conventions exist and both are intentional: + - `Error *error` in the orchestrator, + - `char *message, size_t message_size` across the audio module boundary. +- Messages: lowercase unless the first word is an acronym or format name, no + trailing period, and specific about the artifact: + - `"cannot open input WAV '%s': %s"` + - `"WAV must contain one or two channels (found %u)"` + - `"cannot allocate %zu bytes for %s: %s"` +- Never: "an error occurred", "invalid input", "something went wrong". + +## Memory and resources + +- Every allocation is checked; allocation goes through one helper rather than + scattering `malloc` calls. +- The codebase uses `goto cleanup` (20 occurrences). Follow it: one exit point + per function, every resource released on every path. +- Arithmetic on sizes and offsets is overflow-checked through dedicated + `checked_*` helpers, not raw `+` and `*`. + +## Comments + +The codebase has **zero comments** across all sources and headers. Keep it that +way. + +Add a comment only when the *why* is not recoverable from the code — a +non-obvious constant, a workaround with a named reason, an external format +quirk. Never restate what the next line does. + +## Declarations + +- Declare variables at the point of use, but at the top of a block when they + take part in a `goto cleanup` path. +- One declaration per line. + +## Enforcement + +Written rules only; no formatter, no linter. `scripts/check.sh` does not police +style — the reviewer mentions it and the coder fixes it. diff --git a/.agents/skills/tester.md b/.agents/skills/tester.md new file mode 100644 index 0000000..6276080 --- /dev/null +++ b/.agents/skills/tester.md @@ -0,0 +1,92 @@ +--- +name: tester +description: Use when deciding what to test, adding or updating tests, choosing fixtures, or proving a change works end to end — before claiming a task is done. +whenToUse: After implementation, and whenever a bug fix must gain a regression test. +--- + +# tester + +Separates what can be proven mechanically from what cannot, and makes "it works" +a fact rather than an opinion. + +## Policy + +- **Thorough.** Every change with observable behaviour gets a test. Every bug fix + gets a regression test that fails before the fix and passes after. +- **The model file is available** to tests. Do not design around its absence. +- **The full suite must finish within 10 minutes.** If it would exceed that, + split it and keep the slow part out of the default run. + +## Test levels + +| Level | Lives in | Uses the model | Budget | +| --- | --- | --- | --- | +| Unit | `tests/unit/` | no | seconds | +| Integration | `tests/integration/` | yes | ≤ 8 min total | +| Robustness | `tests/robustness/` | no | ≤ 2 min total | + +## Harness + +`tests/run.sh` — plain POSIX shell, no external test framework. The project's +dependency policy applies to tests too. It must: + +- exit non-zero if any test fails, +- print one line per test with pass/fail, +- accept a filter argument, and a `--quick` flag that skips model-dependent tests, +- build what it needs into `build/`, never into the source tree. + +`tests/run.sh` does not exist yet. Creating it is the first task that adds a +test. + +## What to cover + +- **Unit:** resampling, overlap-add stitching, overflow-safe arithmetic, byte + readers, WAV parsing (PCM 8/16/24/32, float32, extensible), MP3 framing and + gapless trimming, metronome bar synthesis. +- **Integration:** the CLI contract (usage text, exit codes, mutually exclusive + flags, argument order), WAV and MP3 input producing six stems, refusal to + overwrite an existing output directory, `.part` files never surviving a + failure, interrupt handling, metronome output. +- **Robustness:** truncated, corrupt, and adversarial inputs; memory errors + under sanitizers; large inputs at the documented limits. + +## Fixtures + +- Prefer **generated** input: synthesised tones, click tracks, and hand-built + headers. They are small, deterministic, and reviewable. +- Real audio may be used locally but **never committed**. It lives outside the + repo or under an ignored directory. +- Golden outputs are compared by invariant (channel count, sample rate, frame + count, checksum) — not by listening. + +## Determinism + +- Same input must produce byte-identical output. Test it. +- Floating-point comparisons use an explicit tolerance, stated in the test. +- Nothing depends on wall-clock time, locale, or the current directory without + being pinned. + +## What cannot be automated + +Separation *quality* — bleed, artefacts, "does it sound right" — cannot be +asserted by a test. Do not fake a metric for it. + +When such a judgement is part of the acceptance criteria, the report must say +plainly: **"not machine-verified; requires listening"**, with the file to listen +to and what to compare against. That sentence is the honest alternative to a +false pass. + +## Regression rule + +A bug fix includes the failing case as a test. The report shows the test failing +before the fix and passing after. Without that evidence, the fix is unproven. + +## Flaky tests + +A test that fails intermittently is a defect. Fix it or delete it — never retry +it into green. + +## Claiming success + +Never write "tests pass" without the command and its output. If a test was +skipped, say which and why. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..47bfcae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,113 @@ +# stemsep — agent guide + +<!-- +Loaded automatically at the start of every session. Target: <= 140 lines. +Anything that does not fit here belongs in a skill or in docs/. +Layering: non-negotiables > this file > skills > the task spec. +--> + +## 0. Precedence + +1. The **non-negotiables (R1–R7)** override everything: this file, skills, and the task spec. +2. This file overrides skills. Skills override the task spec. +3. On an unresolved conflict: **stop and report**. Never silently pick a side. + +## 1. Non-negotiables + +<!-- RULES:BEGIN — human-only edit zone. Pinned by scripts/check.sh. --> + +- **R1.** Never operate outside the workspace root: no reads, writes, or commands against paths above it. +- **R2.** Never use SSH, contact remote hosts, or use stored credentials without explicit permission for that specific action. +- **R3.** Keep the build warning-free under the project's existing compiler flags. +- **R4.** Never destroy data the task did not create, and never overwrite an existing output directory. +- **R5.** Never claim verification you did not run; every "verified" statement shows the command and its output. +- **R6.** Never modify this block. It is human-only. +- **R7.** Never contradict documented behaviour without updating the documentation in the same change. + +<!-- RULES:END --> + +## 2. Boot sequence + +1. Read this file (automatic). +2. Load `spec` for every non-trivial request. It produces the SPEC the rest of the pipeline consumes. +3. Load `architect` when the change alters structure (see tiers below). +4. Load `coder` and `style` before editing; load `tester` before claiming anything works. +5. Load `reviewer` at the end, in fresh context. + +## 3. Pipeline + +```text +spec -> plan -> implement -> verify -> review -> commit -> report +``` + +- The coordinator runs the pipeline and owns the result. A sub-agent never declares a stage complete. +- **Review precedes commit.** A task ends with exactly one commit. +- Every task leaves a written report in `docs/reports/`. + +## 4. Change tiers + +| Tier | Definition | Required stages | +| --- | --- | --- | +| Trivial | One file, no observable behaviour change, no new module. | implement, verify, commit, report | +| Normal | Observable behaviour change, no new module or dependency. | spec, implement, verify, review, commit, report | +| Architectural | New module, new directory, new dependency, or a change to the CLI surface or output format. | all stages, plus an ADR in `docs/adr/` | + +When in doubt, choose the higher tier. + +## 5. Sub-agents + +- Delegate to gain **independence or breadth**, not because a task is large: + - review of a completed change (always, for Normal and Architectural), + - verification of a claim that the implementer is biased about, + - research spread across several areas that can run in parallel. +- Do **not** delegate edits to the same file, or work that needs this conversation's context. +- Every delegation prompt starts by naming what to read: `AGENTS.md`, the SPEC, and the skills that apply. +- One writer per file at a time. +- **The reviewer is never the implementer** — review runs in fresh context. +- Sub-agents propose. Only the coordinator declares done. + +## 6. Definition of done + +- [ ] Every acceptance criterion in the SPEC maps to evidence. +- [ ] The build was run and its output pasted. +- [ ] The test suite was run and its output pasted. +- [ ] Independent review passed (Normal and Architectural tiers). +- [ ] One commit exists for the task. +- [ ] The report exists in `docs/reports/`. + +## 7. Stop conditions + +Stop and ask — only in these cases, and always with a concrete question: + +- the operation is irreversible or destructive; +- a non-negotiable would have to be broken; +- a SPEC ambiguity changes observable behaviour (decide internal, reversible details yourself); +- a precondition is missing and guessing would silently produce the wrong artifact. + +## 8. Skill routing + +| Skill | Load when | +| --- | --- | +| `spec` | A request needs acceptance criteria. Start here. | +| `architect` | The change alters structure, placement, dependencies, or an external contract. | +| `coder` | Implementing an approved SPEC. | +| `style` | Writing or reading code — alongside `coder` and `reviewer`. | +| `tester` | Deciding what to test or proving a change works. | +| `reviewer` | After implementation, before the commit. | + +## 9. Repo hygiene + +- Never commit build outputs, binaries, media, or model weights (`/stemsep`, `build/`, `dist/`, `*_stems/`, `models/*.onnx`, `*.wav`). +- Never rewrite git history, force-push, or amend someone else's commit. +- Transient artifacts belong in `build/` and `dist/`, which are ignored. + +## 10. Project facts + +<!-- Mutable. Update when the build or layout changes. --> + +- Build: `./build.sh` +- Run: `./stemsep -i <audio_file> -m <music_identifier>` +- Test: `./tests/run.sh` (see `tester`) +- Checks: `./scripts/check.sh` +- Modules: `main.c` (orchestration), `audio.c` (dispatch), `audio_wav.c`, `audio_mp3.c`, `playback.c`, `metronome.c`. Detail in `architect`. +- Nothing is external except `mpv` at runtime; the policy is in `architect`. diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md new file mode 100644 index 0000000..070d144 --- /dev/null +++ b/docs/adr/0000-template.md @@ -0,0 +1,21 @@ +# NNNN — <title> + +- **Status:** proposed | accepted | superseded by NNNN +- **Date:** YYYY-MM-DD +- **Deciders:** <who> + +## Context + +<!-- What forced a decision: a constraint, a bug, a new requirement. --> + +## Decision + +<!-- What was chosen, in one paragraph, stated as a decision rather than an option. --> + +## Alternatives considered + +<!-- What was rejected and why. This is the part that saves future readers. --> + +## Consequences + +<!-- What becomes easier, what becomes harder, what is now forbidden. --> diff --git a/docs/reports/0000-template.md b/docs/reports/0000-template.md new file mode 100644 index 0000000..2a84b2b --- /dev/null +++ b/docs/reports/0000-template.md @@ -0,0 +1,43 @@ +# NNNN — <slug> + +- **Tier:** trivial | normal | architectural +- **Commit:** <sha> +- **Date:** YYYY-MM-DD + +## Request + +<!-- The request, in one sentence, as it arrived. --> + +## SPEC + +```text +<the SPEC block produced by the spec skill> +``` + +## What changed + +<!-- Files, and one line each on why. --> + +## Verification + +<!-- Pasted commands and their output. Never "tests pass" on its own. --> + +```text +$ ./build.sh +<output> + +$ ./tests/run.sh +<output> +``` + +## Review + +<!-- Verdict and any findings that were addressed. --> + +## Not machine-verified + +<!-- What needed listening, or observation, and how a human can check it. --> + +## Deferred + +<!-- Adjacent problems found but not fixed, and the follow-up they need. --> diff --git a/scripts/check.sh b/scripts/check.sh new file mode 100755 index 0000000..0981ef1 --- /dev/null +++ b/scripts/check.sh @@ -0,0 +1,95 @@ +#!/bin/sh +# Mechanical gate for the rules in AGENTS.md. +# +# Usage: ./scripts/check.sh [--quick] +# +# --quick forwards to ./tests/run.sh and skips the slow, model-dependent tests. +# +# Exit 0 only when every gate passes. An unimplemented gate reports SKIP and is +# counted as an unfinished gate, never as a pass. +set -u + +cd -- "$(dirname -- "$0")/.." || exit 1 + +quick=0 +[ "${1:-}" = "--quick" ] && quick=1 + +failures=0 +unfinished=0 +log=$(mktemp) || exit 1 +trap 'rm -f "$log"' EXIT INT TERM + +pass() { printf ' [PASS] %s\n' "$1"; } +fail() { printf ' [FAIL] %s\n' "$1"; failures=$((failures + 1)); } +skip() { printf ' [SKIP] %s\n' "$1"; unfinished=$((unfinished + 1)); } + +printf 'stemsep check%s\n\n' "$([ "$quick" -eq 1 ] && printf ' (quick)')" + +# R3 — the build stays warning-free under the project's own flags. +if ./build.sh >"$log" 2>&1; then + if grep -q 'warning:' "$log"; then + fail "R3 build is warning-free" + grep 'warning:' "$log" | sed 's/^/ /' | head -20 + else + pass "R3 build is warning-free" + fi +else + fail "R3 build succeeds" + tail -20 "$log" | sed 's/^/ /' +fi + +# R6 — the non-negotiables block is human-only and hash-pinned. +pinned_rules_sha="0f013d946549efa3ac75214b2430d32284bacd4f84698ca66b451025aa3f786e" +actual_rules_sha=$(sed -n '/RULES:BEGIN/,/RULES:END/p' AGENTS.md | sha256sum | cut -d' ' -f1) +if [ "$actual_rules_sha" = "$pinned_rules_sha" ]; then + pass "R6 non-negotiables block unchanged" +else + fail "R6 non-negotiables block was modified" + printf ' expected %s\n actual %s\n' \ + "$pinned_rules_sha" "$actual_rules_sha" +fi + +# R5 — a test suite exists and passes. +if [ -x ./tests/run.sh ]; then + if [ "$quick" -eq 1 ]; then + ./tests/run.sh --quick >"$log" 2>&1 + else + ./tests/run.sh >"$log" 2>&1 + fi + if [ $? -eq 0 ]; then + pass "tests pass" + else + fail "tests pass" + tail -30 "$log" | sed 's/^/ /' + fi +else + skip "tests (no tests/run.sh yet - see the tester skill)" +fi + +# Repo hygiene — generated and binary artifacts never enter the repository. +if git rev-parse --git-dir >/dev/null 2>&1; then + offenders=$(git status --porcelain 2>/dev/null | + grep -E '^[[:space:]]*[AM].*\.(onnx|wav|mp3|bin|o|a)$' || true) + tracked=$(git ls-files 2>/dev/null | grep -E '\.(onnx|wav|mp3)$' || true) + + if [ -n "$offenders" ]; then + fail "no build outputs or media staged" + printf '%s\n' "$offenders" | sed 's/^/ /' + elif [ -n "$tracked" ]; then + fail "no media or model weights tracked by git" + printf '%s\n' "$tracked" | sed 's/^/ /' + else + pass "no build outputs, media, or model weights in the repository" + fi +else + skip "repository hygiene (not a git repository)" +fi + +printf '\n%d failure(s), %d unfinished gate(s)\n' "$failures" "$unfinished" +if [ "$failures" -gt 0 ]; then + exit 1 +fi +if [ "$unfinished" -gt 0 ]; then + printf 'Unfinished gates cannot fail yet - this script is not a complete gate.\n' +fi +exit 0 |
