@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/_support/docs/principles/details/p022-test-behavior-not-implementation.md

@@ -0,0 +1,129 @@
+# P022 — Test Behavior, Not Implementation
+
+## Definition
+
+Assert the observable contract of the tested system. Do not assert private methods, data structures,
+or interactions that the contract does not make necessary.
+
+If a refactor preserves system behavior, the system behavior tests usually do not change.
+
+**Aliases:** black-box-oriented testing, implementation-agnostic testing.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Consumer and provider contract testing is a related but different method. It is not an alias for
+this heuristic.
+
+Black-box testing began before unit test frameworks. Many test communities did not recommend tests
+of implementation details. No one source gives this formulation.
+
+## Decision rule
+
+Assert what a caller or user can observe in the contract. When an internal interaction is part of
+the contract, assert that interaction.
+
+## How to apply
+
+- Before you select an assertion, give a name to the scenario and specified result.
+- Exercise a public or approved boundary at the smallest applicable level.
+- Observe return values, durable state, emitted events, or specified side effects.
+- Use fakes or stubs to control dependencies.
+- Do not put call sequences that do not change contract behavior in the test.
+- Keep structural tests only for specified constraints, for example dependency direction or
+  security.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Contract["Consumer contract"] --> Scenario["Give scenario"]
+    Scenario --> Boundary["Exercise supported boundary"]
+    Boundary --> Observe["Observe result or side effect"]
+    Observe --> Assert["Assert necessary behavior"]
+    Refactor["Replace internal mechanics"] --> Assert
+```
+
+## Language examples
+
+The two tests assert stable order without inspection of the sort implementation.
+
+Python:
+
+```python
+def order_records(records: list[tuple[str, int]]) -> list[tuple[str, int]]:
+    return sorted(records, key=lambda record: record[1])
+
+def test_order_is_stable() -> None:
+    records = [("first", 2), ("second", 1), ("third", 2)]
+    assert order_records(records) == [("second", 1), ("first", 2), ("third", 2)]
+```
+
+Rust:
+
+```rust
+fn order_records(records: &mut Vec<(&str, u32)>) {
+    records.sort_by_key(|record| record.1);
+}
+
+#[test]
+fn order_is_stable() {
+    let mut records = vec![("first", 2), ("second", 1), ("third", 2)];
+    order_records(&mut records);
+    assert_eq!(records, vec![("second", 1), ("first", 2), ("third", 2)]);
+}
+```
+
+## Boundaries and tensions
+
+A consumer contract gives observable behavior. An audit event, transaction boundary, or idempotency key
+can be an observable obligation. A user can observe the result without access to that obligation.
+
+Black-box system tests can be slow and have low diagnostic precision. Use more than one test level.
+When the output format is the contract, keep assertions for the full output.
+
+## Examples
+
+### Positive application
+
+A sort test supplies records and asserts specified order and stability. The test does not use sort
+algorithm details or the temporary collection.
+
+### Misuse or counterexample
+
+A test asserts a private call sequence that is not part of the contract. A safe refactor puts two
+internal steps in one step, and the test fails.
+
+### Athena or agent workflow
+
+A helper test asserts exit status, structured output, and file effects. It does not use private
+function names or log sentences that are not part of the contract.
+
+## Related principles
+
+- [P023 — Parameterized / Table-Driven Testing](p023-parameterized-table-driven-testing.md)
+- [P026 — Regression Before Repair](p026-regression-before-repair.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+
+## References
+
+### Source information
+
+- [Fowler, "Mocks Aren't Stubs" (2007)](https://martinfowler.com/articles/mocksArentStubs.html)
+  gives an analysis of state verification, interaction verification, and refactor costs from coupled
+  expectations.
+
+### Applicable information
+
+- [Microsoft, ".NET unit testing best practices"](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
+  recommends tests that use public methods only.
+- [Testing Library, "Guiding Principles"](https://testing-library.com/docs/guiding-principles/)
+  recommends UI tests that follow software operation, not component internals.
+
+### More information
+
+- [Google Engineering Practices, "What to look for in a code review"](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  tells reviewers to make sure that tests detect broken behavior and stay simple.
+
+[Back to the engineering principles catalog](../README.md#p022)

package/skills/_support/docs/principles/details/p023-parameterized-table-driven-testing.md

@@ -0,0 +1,129 @@
+# P023 — Parameterized / Table-Driven Testing
+
+## Definition
+
+Put one behavior rule in one test procedure. Apply that rule to more than one named case with inputs, expected
+results, and related context.
+
+This structure uses one test procedure for its examples.
+
+**Aliases:** data-driven tests, test tables, parameterized tests, theories.
+
+## Provenance
+
+**Classification:** established principle.
+
+Test frameworks and language communities used data-driven tests before the tools available today. The name
+is applicable to two forms. No one source started the method.
+
+## Decision rule
+
+When cases are different mainly because of data, use one clear test procedure. Give each case its
+own name.
+
+## How to apply
+
+- Give each case a diagnostic name that gives the case condition.
+- Store explicit expected results. Do not calculate them with production logic.
+- Include usual, nondefault, empty, missing, rejected, and boundary cases.
+- Keep setup and assertions small for each case. Use a different test for cases that apply a
+  different rule.
+- Isolate mutable case data. Make each failure identify the specified case.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Rule["One behavior rule"] --> Procedure["One test procedure"]
+    Cases["Named input and expected-result cases"] --> Procedure
+    Procedure --> Run["Run each case"]
+    Run --> Result{"Case passes?"}
+    Result -->|No| Name["Report specified case name"]
+    Result -->|Yes| More{"More cases?"}
+    More -->|Yes| Run
+    More -->|No| Success["Test completes"]
+```
+
+## Language examples
+
+The two examples apply one normalization rule to the same named cases.
+
+Python:
+
+```python
+def normalize(value: str) -> str:
+    return value.strip().lower()
+
+def test_normalize_cases() -> None:
+    cases = [("trim", " Yes ", "yes"), ("case", "NO", "no"), ("empty", " ", "")]
+    for name, given, expected in cases:
+        assert normalize(given) == expected, name
+```
+
+Rust:
+
+```rust
+fn normalize(value: &str) -> String {
+    value.trim().to_lowercase()
+}
+
+#[test]
+fn normalize_cases() {
+    let cases = [("trim", " Yes ", "yes"), ("case", "NO", "no"), ("empty", " ", "")];
+    for (name, given, expected) in cases {
+        assert_eq!(normalize(given), expected, "{name}");
+    }
+}
+```
+
+## Boundaries and tensions
+
+When cases use different workflows or many conditional fields, a large table can hide the test objective.
+Do not put different integration scenarios in one loop only to remove lines.
+
+Parameterization adds coverage for selected examples. It does not include all inputs. It does not
+replace property tests or boundary analysis.
+
+## Examples
+
+### Positive application
+
+A parser test uses one public operation for some named cases. Cases include a usual value,
+whitespace, empty input, malformed syntax, and maximum length.
+
+### Misuse or counterexample
+
+One table contains flags that select different setup, invocation, and assertion branches. The test
+loop becomes a second implementation that is not easy to understand.
+
+### Athena or agent workflow
+
+A validator uses named cases for accepted frontmatter, a missing field, an unknown field, and malformed
+YAML. Each case uses one invocation and result check.
+
+## Related principles
+
+- [P022 — Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P024 — Boundary-Value Testing](p024-boundary-value-testing.md)
+- [P025 — Property-Based Testing for Invariants](p025-property-based-testing-for-invariants.md)
+
+## References
+
+### Source information
+
+- [Go project, "TableDrivenTests"](https://go.dev/wiki/TableDrivenTests)
+  records the Go practice of shared test logic with full named case data.
+
+### Applicable information
+
+- [pytest, "How to parametrize fixtures and test functions"](https://docs.pytest.org/en/stable/how-to/parametrize.html)
+  gives parameter sets, generated cases, fixtures, and per-case marks.
+- [JUnit User Guide, "Parameterized Classes and Tests"](https://docs.junit.org/current/writing-tests/parameterized-classes-and-tests.html)
+  gives parameter sources, argument conversion, and named invocations.
+
+### More information
+
+- [Microsoft, ".NET unit testing best practices"](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
+  shows the difference between duplicate test logic and named input and expected-result cases.
+
+[Back to the engineering principles catalog](../README.md#p023)

package/skills/_support/docs/principles/details/p024-boundary-value-testing.md

@@ -0,0 +1,128 @@
+# P024 — Boundary-Value Testing
+
+## Definition
+
+Exercise values at and near transitions, limits, and equivalence partition edges. Defects frequently
+occur where behavior changes.
+
+Applicable cases include values less than, equal to, and more than a threshold. Also include zero,
+one, empty, full, minimum, maximum, overflow, and rejected states.
+
+**Aliases:** boundary value analysis, limit testing, edge testing.
+
+## Provenance
+
+**Classification:** established principle.
+
+Boundary value analysis has a long history in software test literature and certification syllabi.
+Evidence does not give one author as the first person to apply this analysis. Athena gives no first author.
+
+## Decision rule
+
+For each input partition or state transition with a material edge, select cases on each side and
+at the edge. Include representations that can overflow or become empty.
+
+## How to apply
+
+- Use contracts, types, protocols, resource limits, and state transitions to find boundaries.
+- When the contract has last accepted, first rejected, and transition values, test them.
+- When evidence shows an interaction, include adjacent boundary combinations.
+- After rejection, verify returned behavior and state preservation.
+- When examples cannot include the boundary space, use generated or combinatorial methods.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Contract["Contract or state transition"] --> Edge["Find material edge"]
+    Edge --> Less["Select a value less than the edge"]
+    Edge --> At["Select a value at the edge"]
+    Edge --> More["Select a value more than the edge"]
+    Less --> Verify["Verify result and state"]
+    At --> Verify
+    More --> Verify
+```
+
+## Language examples
+
+The two examples verify the same values less than the minimum, at the limits, and more than the
+maximum.
+
+Python:
+
+```python
+def accepts_batch(size: int) -> bool:
+    return 0 <= size <= 100
+
+def test_batch_boundaries() -> None:
+    cases = [(-1, False), (0, True), (99, True), (100, True), (101, False)]
+    for size, expected in cases:
+        assert accepts_batch(size) is expected
+```
+
+Rust:
+
+```rust
+fn accepts_batch(size: i32) -> bool {
+    (0..=100).contains(&size)
+}
+
+#[test]
+fn batch_boundaries() {
+    let cases = [(-1, false), (0, true), (99, true), (100, true), (101, false)];
+    for (size, expected) in cases {
+        assert_eq!(accepts_batch(size), expected);
+    }
+}
+```
+
+## Boundaries and tensions
+
+Tests must use boundary values from correct partitions. Boundary tests do not replace
+usual values between boundaries, semantic invariants, failure injection, or security
+abuse cases.
+
+Do not apply `n - 1`, `n`, and `n + 1` without domain analysis. A continuous, wrapped, or encoded
+domain can make a different definition of adjacency necessary.
+
+## Examples
+
+### Positive application
+
+A batch limit lets a request contain 100 items. Tests include 0, 1, 99, 100, and 101 items. The rejection test
+shows that rejection cannot write only part of the batch.
+
+### Misuse or counterexample
+
+A test includes the maximum integer but ignores the API unit. The API applies its limit after UTF-8
+encoding. Character count and byte count can be different.
+
+### Athena or agent workflow
+
+A bounded workflow test includes zero iterations, one iteration, the configured maximum, and one
+iteration more than the maximum. That case must give a clear terminal failure.
+
+## Related principles
+
+- [P023 — Parameterized / Table-Driven Testing](p023-parameterized-table-driven-testing.md)
+- [P025 — Property-Based Testing for Invariants](p025-property-based-testing-for-invariants.md)
+- [P028 — Test Failure Paths, Not Just Success Paths](p028-test-failure-paths.md)
+
+## References
+
+### Source information
+
+- [NIST, "Fault Classes and Error Detection in Specification Based Testing" (1998)](https://www.nist.gov/publications/fault-classes-and-error-detection-specification-based-testing)
+  examines specification conditions that can show specified fault classes.
+
+### Applicable information
+
+- [ISTQB Certified Tester Foundation Level Syllabus v4.0.1](https://istqb.org/wp-content/uploads/2024/11/ISTQB_CTFL_Syllabus_v4.0.1.pdf)
+  gives two-value and three-value analysis at and near equivalence partition boundaries.
+
+### More information
+
+- [NIST, "Software Fault Complexity and Implications for Software Testing"](https://www.nist.gov/publications/software-fault-complexity-and-implications-software-testing)
+  gives evidence for coverage of interactions in a small group of conditions.
+
+[Back to the engineering principles catalog](../README.md#p024)

package/skills/_support/docs/principles/details/p025-property-based-testing-for-invariants.md

@@ -0,0 +1,133 @@
+# P025 — Property-Based Testing for Invariants
+
+## Definition
+
+Use properties that must hold for a set of input values. Generate many inputs and
+reduce each failure to a small counterexample.
+
+This method can help parsers, serializers, algorithms, transformations, protocols, and state
+machines.
+
+**Aliases:** generative property testing, QuickCheck-style testing.
+
+## Provenance
+
+**Classification:** established principle.
+
+QuickCheck followed random tests and specification-based generators. Claessen and Hughes wrote the
+2000 paper. It gave the library pattern of generators, properties, and shrinking.
+
+## Decision rule
+
+When an invariant gives correctness rules for more inputs than example cases, encode the invariant.
+Generate accepted and rejected inputs from the domain. Preserve reproducible failures.
+
+## How to apply
+
+- Give a property such as round-trip equivalence, order, conservation, or a state
+  invariant.
+- Make generators that represent the domain and include shapes with nested or constrained data.
+- Give rejected combinations. Do not discard most generated inputs.
+- Reduce each failure to a small counterexample. Add each counterexample that helps diagnosis to the
+  regression suite.
+- Record seeds and control external state so each failure is reproducible.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Property["Invariant"] --> Generator["Generate domain inputs"]
+    Generator --> Evaluate["Verify property"]
+    Evaluate --> Result{"Property holds?"}
+    Result -->|Yes| Budget{"All budgeted cases have results?"}
+    Budget -->|No| Generator
+    Budget -->|Yes| Success["Complete run"]
+    Result -->|No| Reduce["Reduce counterexample"]
+    Reduce --> Preserve["Preserve reproducible case"]
+```
+
+## Language examples
+
+The two examples generate sequences of signed 32-bit integers with 0–99 elements and verify the
+same reverse round-trip property.
+
+Python:
+
+```python
+from hypothesis import given
+from hypothesis import strategies as st
+
+@given(st.lists(
+    st.integers(min_value=-(2**31), max_value=2**31 - 1),
+    min_size=0, max_size=99,
+))
+def test_reverse_round_trip(value: list[int]) -> None:
+    encoded = list(reversed(value))
+    assert list(reversed(encoded)) == value
+```
+
+Rust:
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn reverse_round_trip(value in proptest::collection::vec(any::<i32>(), 0..100)) {
+        let encoded: Vec<_> = value.iter().rev().copied().collect();
+        let decoded: Vec<_> = encoded.iter().rev().copied().collect();
+        prop_assert_eq!(decoded, value);
+    }
+}
+```
+
+## Boundaries and tensions
+
+High case volume cannot correct a weak property or biased generator. Use property tests with named
+examples, boundary cases, proofs, fuzz tests, and integration tests.
+
+Do not copy the implementation into the oracle. A finite run without failures does not verify a
+property in an unbounded domain.
+
+## Examples
+
+### Positive application
+
+A serializer property generates accepted domain values. It verifies that decode after encode returns
+an equivalent value. Each failure has a small, reproducible counterexample.
+
+### Misuse or counterexample
+
+A sort property verifies only output length. An implementation can return copies of one element and
+pass this weak property.
+
+### Athena or agent workflow
+
+A parser helper generates accepted frontmatter maps with different key orders. The property verifies
+the same normalized contract without undeclared file or network access.
+
+## Related principles
+
+- [P022 — Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P024 — Boundary-Value Testing](p024-boundary-value-testing.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+
+## References
+
+### Source information
+
+- [Claessen and Hughes, "QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs" (2000)](https://doi.org/10.1145/351240.351266)
+  gave the generator and property library design that many tools use.
+
+### Applicable information
+
+- [Hypothesis documentation, API reference](https://hypothesis.readthedocs.io/en/latest/reference/api.html)
+  gives generation, targeted exploration, stateful invariants, and shrinking controls.
+
+### More information
+
+- [Google XLS, "Exhaustive QuickCheck and fuzz tests"](https://google.github.io/xls/dslx_reference/#quickcheck)
+  shows the differences between property generation, exhaustive checks for small domains, and
+  coverage-guided fuzz tests.
+
+[Back to the engineering principles catalog](../README.md#p025)

package/skills/_support/docs/principles/details/p026-regression-before-repair.md

@@ -0,0 +1,134 @@
+# P026 — Regression Before Repair
+
+## Definition
+
+If safe defect reproduction is possible before implementation repair, add an automated test.
+Make sure that the test fails for the reported cause.
+
+After the repair, make sure that the test passes. Keep the test in the suite to detect recurrence.
+
+**Aliases:** bug-reproduction test, failing regression test.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Automated unit test frameworks followed regression tests. Test-first defect repair is a method in
+TDD and maintenance practice. No one source first gave this formulation.
+
+## Decision rule
+
+Before a repair, capture the smallest contract behavior that reproduces the defect. Make sure
+that the unrepaired revision causes the test to fail.
+
+## How to apply
+
+- Reproduce the symptom at the nearest stable test level.
+- Before implementation work, run the new test. Make sure that it fails for the reported cause.
+- Use the smallest fixture that reproduces the defect.
+- Preserve the defect condition.
+- Repair the root cause. Then run the specified test and the applicable suite.
+- Give the test a behavior name that continues to help after implementation changes.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Report["Defect report"] --> Test["Create small behavior test"]
+    Test --> Red{"Fails for reported cause?"}
+    Red -->|No| Refine["Refine reproduction"]
+    Refine --> Test
+    Red -->|Yes| Repair["Repair root cause"]
+    Repair --> Green{"Specified test passes?"}
+    Green -->|No| Repair
+    Green -->|Yes| Suite["Run applicable suite"]
+```
+
+## Language examples
+
+The two examples preserve the same empty-input regression after the mean calculation repair.
+
+Python:
+
+```python
+def mean(values: list[float]) -> float | None:
+    if not values:
+        return None
+    return sum(values) / len(values)
+
+def test_empty_input_returns_none() -> None:
+    assert mean([]) is None
+```
+
+Rust:
+
+```rust
+fn mean(values: &[f64]) -> Option<f64> {
+    if values.is_empty() {
+        return None;
+    }
+    Some(values.iter().sum::<f64>() / values.len() as f64)
+}
+
+#[test]
+fn empty_input_returns_none() {
+    assert_eq!(mean(&[]), None);
+}
+```
+
+## Boundaries and tensions
+
+Safe reproduction is not possible in each case. Production containment, destructive failures,
+nondeterministic races, or unavailable dependencies can make safe mitigation necessary before reproduction.
+When reproduction with the production dependency is not safe, use a model-based reproduction.
+
+Do not write a test that copies the defective implementation or depends on an accidental symptom. A
+test added only after repair gives weaker evidence. No evidence shows its sensitivity to the
+reported defect.
+
+A regression test is RED on the unrepaired revision and GREEN after repair. A characterization
+test starts GREEN and records behavior before a behavior-preserving refactor. These tests have
+related but different objectives.
+
+## Examples
+
+### Positive application
+
+A parser report includes one malformed input. A small test of the public API first reproduces the
+exception. The test passes after the parser returns the specified structured error.
+
+### Misuse or counterexample
+
+A developer adds a test after the code change. The test passes on each revision. It does not give
+evidence of regression sensitivity.
+
+### Athena or agent workflow
+
+An agent records the failed command and output. The agent makes the smallest necessary repair. Then,
+the agent runs that test again. If the test passes, the agent runs the repository gate.
+
+## Related principles
+
+- [P021 — Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md)
+- [P022 — Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+- [P091 — Test-Driven Development](p091-test-driven-development.md)
+
+## References
+
+### Source information
+
+- [Beck, *Test-Driven Development: By Example* (2002)](https://www.pearson.com/en-us/subject-catalog/p/Beck-Test-Driven-Development-By-Example/P200000009421/9780321146533)
+  gives a widely used test-first cycle that also applies to defect repair.
+
+### Applicable information
+
+- [Google Engineering Practices, "Small CLs"](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  gives pre-refactor guidance for tests of behavior changes and missing behavioral coverage.
+
+### More information
+
+- [Microsoft, ".NET unit testing best practices"](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
+  gives information about regression protection and repeatable, self-checking tests.
+
+[Back to the engineering principles catalog](../README.md#p026)