@homericintelligence/athena-opencode 0.5.0 → 0.5.1

package/skills/_support/docs/principles/details/p027-deterministic-and-hermetic-tests.md

@@ -0,0 +1,128 @@
+# P027 — Deterministic and Hermetic Tests
+
+## Definition
+
+Use controlled inputs and isolation from undeclared external influences to make tests repeatable.
+Such influences include time, random values, environment variables, file state, networks, locale,
+concurrency, and shared services.
+
+Tests must give the same result for each execution order.
+
+**Aliases:** isolated tests, reproducible tests, hermetic testing.
+
+## Provenance
+
+**Classification:** established principle.
+
+Software test guidance includes determinism and isolation. Large build and test systems use the term
+"hermetic." No one source gives this full formulation.
+
+## Decision rule
+
+If an external input can change a result, the test must declare or control that input. The test must
+not share mutable state between executions.
+
+## How to apply
+
+- If a clock, random generator, environment, or external client can change a result, inject that input.
+- Use temporary resources for each test and deterministic cleanup.
+- Use controlled local substitutes, not live networks. Use live networks only in specified
+  integration or acceptance suites.
+- Record seeds and schedules for generated or concurrent tests. Preserve each counterexample.
+- Run tests individually and in different orders.
+- If the test harness can run tests in parallel, use parallel execution.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Test["Test case"] --> Inputs["Declare or control inputs"]
+    Inputs --> Isolate["Isolate mutable resources"]
+    Isolate --> Execute["Run many times"]
+    Execute --> Same{"Same result?"}
+    Same -->|Yes| Valid["Repeatable test"]
+    Same -->|No| Influence["Find undeclared influence"]
+    Influence --> Inputs
+```
+
+## Language examples
+
+The two examples inject the same clock value and do not read the wall clock.
+
+Python:
+
+```python
+def expired(expires_at: int, now: int) -> bool:
+    return now >= expires_at
+
+def test_expiry_with_controlled_time() -> None:
+    assert expired(100, 100)
+    assert not expired(101, 100)
+```
+
+Rust:
+
+```rust
+fn expired(expires_at: u64, now: u64) -> bool {
+    now >= expires_at
+}
+
+#[test]
+fn expiry_with_controlled_time() {
+    assert!(expired(100, 100));
+    assert!(!expired(101, 100));
+}
+```
+
+## Boundaries and tensions
+
+Deterministic and hermetic are related but different. If a fixed external service gives the same
+input, a nonhermetic test can be deterministic. A hermetic test can use uncontrolled random values.
+
+Full isolation can hide integration failures. Keep specified nonhermetic suites in
+controlled environments. Retries can diagnose flaky behavior, but they cannot make an unreliable
+test reliable.
+
+## Examples
+
+### Positive application
+
+A cache-expiry test receives a fake clock and a new temporary directory. The test controls clock
+changes. Machine time zone and test order cannot change the result.
+
+### Misuse or counterexample
+
+A test uses a public web service and retries until success. Availability, remote data, DNS, and
+rate limits control the result.
+
+### Athena or agent workflow
+
+A repository validator test creates an isolated fixture tree and supplies each environment value.
+The helper does not use a user checkout or network credentials.
+
+## Related principles
+
+- [P022 — Test Behavior, Not Implementation](p022-test-behavior-not-implementation.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
+
+- [Google Testing Blog, "Hermetic Servers" (2012)](https://testing.googleblog.com/2012/10/hermetic-servers.html)
+  gives information about isolation from live network dependencies in end-to-end tests.
+
+### Applicable information
+
+- [Bazel, "Hermeticity"](https://bazel.build/basics/hermeticity)
+  gives declared inputs, fixed environment properties, and isolation for deterministic results.
+- [Microsoft, ".NET unit testing best practices"](https://learn.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices)
+  gives isolation and repeatability as core test characteristics.
+
+### More information
+
+- [Google Testing Blog, "Flaky Tests at Google and How We Mitigate Them" (2016)](https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html)
+  gives causes and operational costs of nondeterministic test results.
+
+[Back to the engineering principles catalog](../README.md#p027)

package/skills/_support/docs/principles/details/p028-test-failure-paths.md

@@ -0,0 +1,133 @@
+# P028 — Test Failure Paths, Not Just Success Paths
+
+## Definition
+
+Verify system behavior for malformed inputs, failed dependencies, and failed operations. Include
+cancellation, timeout, progress before failure, unavailability, retry, cleanup,
+authorization, and resource exhaustion.
+
+Verify success behavior with its own baseline.
+
+**Aliases:** negative testing, robustness testing, error-path testing.
+
+## Provenance
+
+**Classification:** established principle.
+
+Sources for negative tests and robustness tests include reliability, security, and protocol work.
+No one source gives all failure conditions in this principle.
+
+## Decision rule
+
+Find failures that can occur for each material dependency or state transition. Verify the contract
+result, preserved invariants, cleanup, and diagnostic evidence.
+
+## How to apply
+
+- Use contracts and architecture to find failures. Do not use coverage percentages.
+- Inject dependency errors, timeouts, and cancellations.
+- After an operation makes progress, inject a stop.
+- After failure, assert caller-visible error semantics and durable state.
+- Verify resource release. Keep retries and compensation in their budgets.
+- Include authorization denial and malformed untrusted input without live operations that are not safe.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Boundary["Dependency or state transition"] --> Failures["Find possible failures"]
+    Failures --> Inject["Inject controlled fault"]
+    Inject --> Result["Assert error contract"]
+    Result --> State["Verify state and cleanup"]
+    State --> Budget["Verify retry or compensation budget"]
+```
+
+## Language examples
+
+The two examples simulate a write failure, preserve the previous data, and return the cause.
+
+Python:
+
+```python
+from collections.abc import Callable
+def replace(current: str, write: Callable[[], str]) -> tuple[str, Exception | None]:
+    try:
+        return write(), None
+    except OSError as cause:
+        return current, cause
+def test_failure_preserves_current() -> None:
+    cause = OSError("disk full")
+    def fail() -> str:
+        raise cause
+    value, error = replace("old", fail)
+    assert value == "old" and error is cause
+```
+
+Rust:
+
+```rust
+fn replace<F>(current: &str, write: F) -> (String, Option<&'static str>)
+where F: FnOnce() -> Result<String, &'static str> {
+    match write() {
+        Ok(value) => (value, None),
+        Err(cause) => (current.to_owned(), Some(cause)),
+    }
+}
+#[test]
+fn failure_preserves_current() {
+    let result = replace("old", || Err("disk full"));
+    assert_eq!(result, ("old".to_owned(), Some("disk full")));
+}
+```
+
+## Boundaries and tensions
+
+Do not cause destructive production failures for test evidence. Use controlled substitutes,
+sandboxes, fault injection, or staged environments that the approved risk policy specifies.
+
+Mock failures can be different from dependency behavior in production. When mock behavior changes
+the contract, add contract or integration evidence. Do not show sensitive internal details in caller-visible errors.
+
+## Examples
+
+### Positive application
+
+A file replacement test injects a write failure after the write operation creates temporary output. It verifies that
+the previous file is correct. It also verifies cleanup and cause preservation.
+
+### Misuse or counterexample
+
+A client has many success-path tests but no test for a timeout after a committed write. An automatic
+retry can duplicate the operation.
+
+### Athena or agent workflow
+
+A skill test simulates a missing necessary capability. It verifies a clear, safe failure response.
+The test verifies that the skill does not skip work or return success without evidence.
+
+## Related principles
+
+- [P022 — Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+- [P030 — Handle Errors at the Nearest Responsible Boundary](p030-nearest-responsible-error-boundary.md)
+
+## References
+
+### Source information
+
+- [NIST, "An Approach for Analyzing the Robustness of Windows NT Software" (1998)](https://csrc.nist.gov/files/pubs/conference/1998/10/08/proceedings-of-the-21st-nissc-1998/final/docs/paperf8.pdf)
+  gives robustness tests with accepted inputs, rejected inputs, and exception conditions.
+
+### Applicable information
+
+- [Google Engineering Practices, "What to look for in a code review"](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  says tests must detect broken behavior.
+- [OWASP Web Security Testing Guide, "Testing for Error Handling"](https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/08-Testing_for_Error_Handling/README)
+  gives security tests for incorrect error responses and stack disclosure.
+
+### More information
+
+- [OWASP, "Business Logic Security Cheat Sheet"](https://cheatsheetseries.owasp.org/cheatsheets/Business_Logic_Security_Cheat_Sheet.html)
+  adds adversarial cases for incorrect order, steps that occur again, concurrency, and rule bypass.
+
+[Back to the engineering principles catalog](../README.md#p028)

package/skills/_support/docs/principles/details/p029-generalize-error-policy-preserve-specific-cause.md

@@ -0,0 +1,131 @@
+# P029 — Generalize Error Policy; Preserve Specific Cause
+
+## Definition
+
+Use a small taxonomy for stable errors at architectural boundaries. Preserve the initial cause,
+stack, and safe structured context for diagnosis.
+
+A general policy helps callers select a response. A specific cause helps operators diagnose the
+failed event.
+
+**Aliases:** error translation with cause preservation, layered error taxonomy.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Sources are different for exception chains, causal errors, and protocol problem taxonomies.
+No historical source gives this full rule.
+
+## Decision rule
+
+At a boundary that owns caller policy, translate a low-level failure. Map the failure to stable
+caller policy. Attach the initial cause with non-sensitive diagnostic context.
+
+## How to apply
+
+- Give a bounded error set that lets callers select responses, for example rejected input, unavailable,
+  or conflict.
+- Translate vendor and transport failures at the boundary that owns the public contract.
+- Preserve causal links and structured fields for operators.
+- Keep retry status and user messages different from exception text that can change.
+- Remove secrets and internal details from public results. Keep safe internal evidence.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Failure["Low-level failure"] --> Boundary{"Boundary owns caller policy?"}
+    Boundary -->|No| Propagate["Preserve and propagate cause"]
+    Boundary -->|Yes| Policy["Map to stable error policy"]
+    Policy --> Public["Return safe public error"]
+    Policy --> Evidence["Keep specific internal cause"]
+```
+
+## Language examples
+
+The two examples map a storage timeout to an unavailable error and preserve the specific cause.
+
+Python:
+
+```python
+class StorageTimeout(RuntimeError):
+    pass
+
+class UnavailableError(RuntimeError):
+    pass
+
+def load(fetch):
+    try:
+        return fetch()
+    except StorageTimeout as cause:
+        raise UnavailableError("storage unavailable") from cause
+```
+
+Rust:
+
+```rust
+#[derive(Debug)]
+struct StorageTimeout;
+
+#[derive(Debug)]
+struct UnavailableError { message: &'static str, source: StorageTimeout }
+
+fn load(result: Result<String, StorageTimeout>) -> Result<String, UnavailableError> {
+    result.map_err(|source| UnavailableError { message: "storage unavailable", source })
+}
+```
+
+## Boundaries and tensions
+
+One `operation failed` result is too general when callers must select different responses. Each
+dependency exception is too specific and couples consumers to internal details.
+
+Cause preservation does not authorize disclosure of stacks, paths, queries, credentials, or
+personal data. Use approved decisions to change stable taxonomies. Do not add one type for
+each event.
+
+## Examples
+
+### Positive application
+
+A storage timeout becomes a public `temporarily-unavailable` problem. The response includes a
+correlation ID and retry policy. The internal record preserves the driver error and operation context.
+
+### Misuse or counterexample
+
+A handler converts each exception to a `null` response with success status. This conversion erases the
+error policy and cause. A second handler sends the full database stack to the client.
+
+### Athena or agent workflow
+
+A dependency helper returns one specified unavailable status. Its diagnostic record identifies
+the checkout, command, exit status, and causal error. The record excludes secrets.
+
+## Related principles
+
+- [P019 — Explicit Contracts](p019-explicit-contracts.md)
+- [P028 — Test Failure Paths, Not Just Success Paths](p028-test-failure-paths.md)
+- [P030 — Handle Errors at the Nearest Responsible Boundary](p030-nearest-responsible-error-boundary.md)
+
+## References
+
+### Source information
+
+- [PEP 3134, "Exception Chaining and Embedded Tracebacks" (2005)](https://peps.python.org/pep-3134/)
+  records explicit causal links and context for a new exception after a second exception.
+
+### Applicable information
+
+- [RFC 9457, "Problem Details for HTTP APIs" (2023)](https://www.rfc-editor.org/rfc/rfc9457.html)
+  gives stable problem types and event-specific details. The RFC gives a warning about exposure of
+  implementation details.
+- [Python documentation, "Exception context"](https://docs.python.org/3/library/exceptions.html#exception-context)
+  gives implicit and explicit exception chain semantics.
+
+### More information
+
+- [OWASP, "Error Handling Cheat Sheet"](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html)
+  shows the difference between safe external errors and detailed internal diagnostics for investigation.
+
+[Back to the engineering principles catalog](../README.md#p029)

package/skills/_support/docs/principles/details/p030-nearest-responsible-error-boundary.md

@@ -0,0 +1,133 @@
+# P030 — Handle Errors at the Nearest Responsible Boundary
+
+## Definition
+
+Handle an error only where policy and context are sufficient for correct recovery, retry,
+compensation, translation, or termination. A lower layer frequently detects a failure first.
+
+When the lower layer cannot select the correct result, it must propagate the failure.
+
+**Aliases:** catch where you can handle, responsible error boundary.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Exception systems use stack-based handler selection. Language communities gave related rules
+about error propagation. No one source first gave this formulation.
+
+## Decision rule
+
+At the first boundary that can satisfy the caller's contract and preserve correct state, handle the
+failure. If the boundary cannot satisfy the contract or preserve correct state, add applicable safe
+context. After the boundary adds the context, propagate the failure.
+
+## How to apply
+
+- Detection, cleanup, translation, recovery, and caller presentation are different operations.
+- When a layer owns a recovery or contract decision, the layer can catch the error.
+- Use deterministic cleanup constructs. Cleanup does not recover the operation.
+- After translation, preserve the cause. Do not record the same failure at each layer.
+- Put retries at the boundary that knows idempotency, deadlines, and dependency semantics.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Detect["Layer detects failure"] --> Decide{"Boundary owns result policy?"}
+    Decide -->|No| Context["Add applicable safe context"]
+    Context --> Propagate["Propagate failure"]
+    Decide -->|Yes| Policy["Apply boundary policy"]
+    Policy --> Action["Recover, retry, translate, or terminate"]
+    Action --> State["Preserve correct state"]
+```
+
+## Language examples
+
+The two examples put retry policy in the caller of a low-level read operation that propagates its
+error.
+
+Python:
+
+```python
+def read_once(client):
+    return client.read()
+
+def read_with_retry(client):
+    try:
+        return read_once(client)
+    except TimeoutError:
+        return read_once(client)
+```
+
+Rust:
+
+```rust
+trait Client { fn read(&mut self) -> Result<String, TimeoutError>; }
+struct TimeoutError;
+fn read_once(client: &mut impl Client) -> Result<String, TimeoutError> {
+    client.read()
+}
+
+fn read_with_retry(client: &mut impl Client) -> Result<String, TimeoutError> {
+    match read_once(client) {
+        Ok(value) => Ok(value),
+        Err(_) => read_once(client),
+    }
+}
+```
+
+## Boundaries and tensions
+
+The first `catch` site is not always the responsible boundary. A top-level boundary can convert an
+unhandled error to a process exit, protocol response, or job status.
+
+A lower-level operation can do cleanup and preserve the failure. Security policy can make a generic
+public result and restricted internal diagnostics necessary.
+
+## Examples
+
+### Positive application
+
+A repository propagates a database timeout. The service knows that the operation is read-only and
+has a deadline. It makes one bounded retry.
+
+The API boundary converts an exhausted retry budget to a public error with an unavailable status.
+
+### Misuse or counterexample
+
+A low-level parser catches each exception, records it, and returns an empty object. Callers cannot
+tell permitted empty input from corrupt input.
+
+### Athena or agent workflow
+
+A helper returns a typed capability failure. The skill owns fallback policy. It selects the
+specified degraded path or a safe stop and returns the result.
+
+## Related principles
+
+- [P028 — Test Failure Paths, Not Just Success Paths](p028-test-failure-paths.md)
+- [P029 — Generalize Error Policy; Preserve Specific Cause](p029-generalize-error-policy-preserve-specific-cause.md)
+- [P019 — Explicit Contracts](p019-explicit-contracts.md)
+
+## References
+
+### Source information
+
+- [Goodenough, "Exception Handling: Issues and a Proposed Notation" (1975)](https://doi.org/10.1145/361227.361230)
+  gives a full treatment from 1975 of exception detection, handler selection, and recovery.
+
+### Applicable information
+
+- [Microsoft, ".NET best practices for exceptions"](https://learn.microsoft.com/en-us/dotnet/standard/exceptions/best-practices-for-exceptions)
+  recommends a catch for recovery or cleanup. When code at the boundary cannot recover, the guidance
+  recommends propagation.
+- [Microsoft, "Exceptions and Exception Handling"](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/exceptions/)
+  says that a handler rethrows if it cannot keep the application in a known state.
+
+### More information
+
+- [Go Blog, "Error handling and Go"](https://go.dev/blog/error-handling-and-go)
+  shows explicit propagation and caller-related context without loss of the failure.
+
+[Back to the engineering principles catalog](../README.md#p030)

package/skills/_support/docs/principles/details/p031-propagate-rather-than-swallow.md

@@ -0,0 +1,131 @@
+# P031 — Propagate Rather Than Swallow
+
+## Definition
+
+If a layer cannot satisfy all specified postconditions after recovery, it must propagate the
+failure to a responsible boundary. The layer can use its specified interface to return, throw, or
+signal the failure.
+
+The layer must not give a success result, return an empty value, or continue work after a failure.
+The contract must show the difference between success and a failure that the caller must handle.
+
+**Aliases:** error propagation, no silent catch, surface unrecovered failures
+
+## Provenance
+
+**Classification:** established principle.
+
+Authors wrote about structured exception handling for many years. Athena cannot identify one source
+for this phrase. Athena uses it as a language-neutral decision rule.
+
+## Decision rule
+
+If this boundary can satisfy its specified postconditions or give a specified alternative
+result, handle the failure. If the boundary cannot do this, propagate the failure and keep its cause.
+
+## How to apply
+
+- Give failure behavior in return types, exceptions, result objects, exit statuses, or
+  protocol responses.
+- When the layer has the necessary policy context, it can retry, compensate, translate, or stop
+  after a failure.
+- Keep the initial cause during error translation. Add stable context that helps the caller.
+- Give fallback values in the interface. When the contract includes an alternative outcome, give
+  its fallback as a success result.
+- Make sure that dependency failures give a public failure outcome and keep correct state.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["An operation detects a failure"] --> B{"Can this boundary satisfy the contract?"}
+    B -- "Yes" --> C["Recover or return a specified alternative result"]
+    B -- "No" --> D["Add safe context and keep the cause"]
+    D --> E["Propagate the failure to a responsible boundary"]
+```
+
+## Language examples
+
+Each example adds caller context and keeps a failure outcome.
+
+### Python
+
+```python
+def load_record(store, key):
+    try:
+        return store.read(key)
+    except StorageError as error:
+        raise RecordLoadError(key) from error
+```
+
+### Rust
+
+```rust
+fn load_record(store: &Store, key: &str) -> Result<Record, RecordLoadError> {
+    store
+        .read(key)
+        .map_err(|source| RecordLoadError::new(key, source))
+}
+```
+
+## Boundaries and tensions
+
+A boundary can translate an internal error into a stable taxonomy. It must keep the causal chain.
+Use [P032](p032-handle-once-preserve-causality.md) for cause preservation.
+
+[P036](p036-graceful-degradation.md) gives conditions for a safe reduced mode. The mode is
+applicable only when the contract includes it as an alternative outcome.
+
+Use [P035](p035-fail-secure-fail-closed.md) for security uncertainty. Do not show secrets or
+credentials. If the caller contract does not include internal information, do not show it. Keep
+necessary cause data in protected diagnostics.
+
+## Examples
+
+### Positive application
+
+A repository adapter cannot read a necessary record. It attaches the record identifier to the
+storage error and returns the error. The service boundary maps the failure to its specified API
+error. Protected diagnostics keep the initial cause.
+
+### Misuse or counterexample
+
+A configuration loader catches each parse error and returns an empty configuration. Startup gives
+a success result. The service operates with invalid values. Engineers cannot find the initial
+failure.
+
+### Athena or agent workflow
+
+If a necessary validation command returns a nonzero status, an Athena workflow records the command
+and its results. The workflow does not give a success result because other checks had correct results.
+
+## Related principles
+
+- [P032 — Handle Once; Preserve Causality](p032-handle-once-preserve-causality.md)
+- [P033 — State-Safe Failure Semantics](p033-state-safe-failure-semantics.md)
+- [P034 — Fail Fast](p034-fail-fast.md)
+- [P036 — Graceful Degradation](p036-graceful-degradation.md)
+
+## References
+
+### Source information
+
+- [John B. Goodenough, “Structured Exception Handling” (1975)](https://doi.org/10.1145/512976.512997)
+  — a 1975 analysis of exception conditions and control transfer to a handler with the necessary
+  context. This source is not the source of Athena's phrase.
+
+### Applicable information
+
+- [The Rust Programming Language: Propagating Errors](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#propagating-errors)
+  — official guidance for a callee that returns an error when its caller has the necessary decision
+  context.
+- [C++ Core Guidelines, Error Handling](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-errors)
+  — guidance that recommends a specified error strategy. It recommends no handler in each
+  function.
+
+### More information
+
+- [P029 — Generalize Error Policy; Preserve Specific Cause](../README.md#p029) — the catalog rule
+  for error translation that keeps diagnostic specificity.
+
+[Back to the engineering principles catalog](../README.md#p031)