@homericintelligence/athena-opencode 0.5.0 → 0.5.1

package/skills/_support/docs/principles/details/p080-make-concurrency-deliberate.md

@@ -0,0 +1,122 @@
+# P080 — Make Concurrency Deliberate
+
+## Definition
+
+Measurements must first give proof of a benefit. **Make Concurrency Deliberate** then lets a design
+use parallel or asynchronous execution. The design gives the full coordination model. The model includes shared state,
+synchronization, order, cancellation, deadlines, error collection, and capacity limits.
+
+**Aliases:** none.
+
+## Provenance
+
+**Classification:** principle with source evidence.
+
+No source gives this text. The rule uses research on processes, synchronization, messages,
+structured concurrency, and language memory models. This research gives evidence that concurrency
+changes the correctness model. The design must include explicit analysis.
+
+## Decision rule
+
+As the default, use sequential execution. Use concurrency only for a measured latency, throughput,
+response, or isolation benefit. Select a model with testable safety and termination properties.
+
+## How to apply
+
+- Record the specified benefit. Measure the latency, throughput, response, or isolation change.
+- Use the minimum shared mutable state. Use immutable messages or ownership transfer.
+- Give order guarantees, synchronization, and permitted interleavings.
+- Set limits for workers, queues, fan-out, and active work.
+- Propagate deadlines and cancellation to all tasks in the tree.
+- Give one result for failures and concurrent errors.
+- Where applicable, use race detection, stress tests, and deterministic model tests.
+
+## Diagram
+
+After measurements give proof of a benefit, the design adds concurrency.
+
+```mermaid
+flowchart LR
+    A["Sequential design"] --> B{"Measured benefit?"}
+    B -->|No| C["Keep sequential flow"]
+    B -->|Yes| D["Owners and limits"]
+    D --> E["Order and cancellation"]
+    E --> F["Do bounded concurrent work"]
+    F --> G["Collect all results"]
+```
+
+## Language examples
+
+The two examples await two ordered operations, return each result, and cancel child operations when the caller stops.
+
+### Python
+
+```python
+FetchResult = bytes | BaseException
+
+async def fetch_pair(urls: tuple[str, str]) -> tuple[FetchResult, FetchResult]:
+    results = await asyncio.gather(
+        fetch(urls[0]), fetch(urls[1]), return_exceptions=True
+    )
+    return results[0], results[1]
+```
+
+### Rust
+
+```rust
+type FetchResult = Result<Body, Error>;
+
+async fn fetch_pair(urls: [&str; 2]) -> (FetchResult, FetchResult) {
+    let results = tokio::join!(fetch(urls[0]), fetch(urls[1]));
+    results
+}
+```
+
+## Boundaries and tensions
+
+When concurrent callers or external systems use sequential code, the code can have races. Concurrency is
+necessary in some domains. The principle gives a specified model and lets a design use concurrency.
+If measured speed benefits increase correctness risk or operation cost, reject the benefits. An asynchronous
+interface must not cause concurrency in other layers.
+
+## Examples
+
+**Positive:** A bounded operation starts two reads that operate independently with a shared deadline. The
+reads have no shared mutable state. The result order is deterministic.
+
+**Misuse:** A loop starts one worker for each input without a limit. The loop discards failures, and
+the caller cannot cancel the work.
+
+**Athena/agent workflow:** A coordinator delegates only subtasks that can operate independently. The
+coordinator gives each worker bounded scope. Before the coordinator accepts shared conclusions, the
+coordinator collects and compares all results.
+
+## Related principles
+
+- [P039 Bounded Waiting](p039-bounded-waiting.md)
+- [P040 Bounded Resources](p040-bounded-resources.md)
+- [P042 Fault Isolation / Bulkheads](p042-fault-isolation-bulkheads.md)
+- [P079 Explicit Ownership and Lifetimes](p079-explicit-ownership-and-lifetimes.md)
+- [P082 Design for Cancellation](p082-design-for-cancellation.md)
+
+## References
+
+### Source information
+
+- [Communicating Sequential Processes](https://doi.org/10.1145/359576.359585) is C. A. R. Hoare's
+  1978 primary paper that gives a process-and-message model without implicit shared-state
+  coordination.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  includes concurrency as a complexity and correctness area for careful inspection.
+- [The Rust Programming Language: Fearless Concurrency](https://doc.rust-lang.org/book/ch16-00-concurrency.html)
+  gives examples of ownership and types that prevent many concurrency errors.
+
+### More information
+
+- [Go Concurrency Patterns: Context](https://go.dev/blog/context) gives information about explicit
+  propagation of deadlines and cancellation to all concurrent request work.
+
+[Back to the engineering principles catalog](../README.md#p080)

package/skills/_support/docs/principles/details/p081-forward-progress-with-safety.md

@@ -0,0 +1,125 @@
+# P081 — Forward Progress With Safety
+
+## Definition
+
+With **Forward Progress With Safety**, an operation must have bounded and clear progress to a
+correct result. If progress stops, the operation terminates in a clear recoverable state. The rule
+includes safety and liveness properties.
+
+**Aliases:** none.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Athena gives this rule for operations. The rule is not a theorem with a specified name. Leslie Lamport's 1977
+research gives the difference between safety and liveness properties. Reliability practice includes deadlines, retry
+budgets, cancellation, and recovery states for production workflows.
+
+## Decision rule
+
+For each loop, wait, retry, queue, and multistep workflow, give a progress measure and a bound.
+Record the necessary invariants. Give a recoverable result for stopped progress.
+
+## How to apply
+
+- Use different results for terminal success, failure, cancellation, and paused states.
+- Set limits for retries, waits, queues, and internal iteration.
+- Monitor progress and record each stagnation event. Do not reset a watchdog without measured progress.
+- Keep invariants at all checkpoints and failure exits.
+- When necessary, record sufficient state to resume long work safely.
+- Do tests of deadlock, timeout, starvation, cancellation, and dependency-loss scenarios.
+
+## Diagram
+
+The workflow makes measured progress or has a recoverable terminal state.
+
+```mermaid
+flowchart LR
+    A["Start bounded work"] --> H["Do next bounded work unit"]
+    H --> B{"Progress?"}
+    B -->|Yes| C{"Work completed?"}
+    C -->|No| H
+    C -->|Yes| D["Correct result"]
+    B -->|No| E{"Retry budget has capacity?"}
+    E -->|Yes| F["Do recovery step"]
+    F --> H
+    E -->|No| G["Recoverable failure"]
+```
+
+## Language examples
+
+The two examples stop after a fixed number of attempts and return a clear failure.
+
+### Python
+
+```python
+def complete(job: Job) -> Result:
+    for _ in range(3):
+        result = job.try_once()
+        if result.done:
+            return result
+    raise ProgressError("retry budget exhausted")
+```
+
+### Rust
+
+```rust
+fn complete(job: &mut Job) -> Result<Outcome, ProgressError> {
+    for _ in 0..3 {
+        let result = job.try_once()?;
+        if result.done {
+            return Ok(result);
+        }
+    }
+    Err(ProgressError::BudgetExhausted)
+}
+```
+
+## Boundaries and tensions
+
+A wait-free algorithm and a short duration are not necessary. Some safe work is slow or
+waits for external events. Clear state, cancellation, or an explicit resume state is necessary.
+Safety can make the operation stop. A timeout is a failure result. The timeout does not give proof
+that a side effect did not occur.
+
+## Examples
+
+**Positive:** A migration records each completed batch and sets a time budget. The migration keeps schema
+invariants and stops with a `paused` status and resume token.
+
+**Misuse:** A worker catches each error and retries without a limit. The worker keeps a queue slot. Callers
+see no completion or failure.
+
+**Athena/agent workflow:** A delegated task has a bounded iteration budget. The task gives success,
+blocked, or failure status with evidence. The task does not stay active without a limit.
+
+## Related principles
+
+- [P039 Bounded Waiting](p039-bounded-waiting.md)
+- [P040 Bounded Resources](p040-bounded-resources.md)
+- [P046 Resumability](p046-resumability.md)
+- [P047 Observability Is Part of Correctness](p047-observability-is-part-of-correctness.md)
+- [P082 Design for Cancellation](p082-design-for-cancellation.md)
+
+## References
+
+### Source information
+
+- [Proving the Correctness of Multiprocess Programs](https://doi.org/10.1109/TSE.1977.229904)
+  is Lamport's 1977 primary paper that gives safety and liveness as different correctness concerns.
+
+### Applicable information
+
+- [gRPC Deadlines](https://grpc.io/docs/guides/deadlines/) gives information about call deadlines.
+  Call deadlines must agree with the specified duration. Servers must stop work after cancellation.
+- [AWS Well-Architected: Control and limit retry calls](https://docs.aws.amazon.com/wellarchitected/latest/framework/rel_mitigate_interaction_failure_limit_retries.html)
+  gives retry limits, backoff, and tested stop conditions.
+
+### More information
+
+- [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)
+  gives a bounded randomized retry method. The method decreases synchronized contention and helps
+  progress.
+
+[Back to the engineering principles catalog](../README.md#p081)

package/skills/_support/docs/principles/details/p082-design-for-cancellation.md

@@ -0,0 +1,133 @@
+# P082 — Design for Cancellation
+
+## Definition
+
+With **Design for Cancellation**, an interface includes a caller's loss of interest as a terminal
+signal. The designer gives the cancellation request, propagation path, cleanup, and
+terminal result for long or asynchronous work. Cancellation must keep state correct and must not
+cause a resource leak.
+
+**Aliases:** none. Cooperative cancellation is one implementation method.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+No source records an initial author. Operating systems, concurrent programs, and distributed request
+interfaces use cooperative cancellation. Structured concurrency and context interfaces
+make the lifetime relation between callers and child work explicit.
+
+## Decision rule
+
+If work can continue after the caller request stops, give the work a cancellation contract. Tell the
+cancellation point. Tell the cleanup guarantee and the terminal result.
+
+## How to apply
+
+- Accept and propagate the host's cancellation or context capability.
+- Monitor cancellation at bounded, state-safe checkpoints.
+- After the cancellation signal, do not start more work.
+- Release resources and join child work or record each child result. Then return.
+- Use different results for cancellation, timeout, dependency failure, and completion without error.
+- When signals can occur again and again, make cleanup, compensation, and retries idempotent.
+- Do tests of races between cancellation, completion, and side effects that stop before completion.
+
+## Diagram
+
+The worker releases the worker resources after cancellation or completion.
+
+```mermaid
+flowchart LR
+    A["Work in progress"] --> B{"Cancellation signal?"}
+    B -->|Yes| D["Complete safe checkpoint"]
+    D --> E["Release resources"]
+    E --> F["Cancellation result"]
+    B -->|No| C{"Work completed?"}
+    C -->|No| G["Do next bounded unit"]
+    G --> A
+    C -->|Yes| H["Release resources"]
+    H --> I["Success result"]
+```
+
+## Language examples
+
+The two examples monitor one cancellation signal, keep operation failures distinct, and release
+resources on cancellation and completion.
+
+### Python
+
+```python
+async def import_rows(cancel: asyncio.Event) -> None:
+    try:
+        for batch in batches:
+            if cancel.is_set():
+                raise asyncio.CancelledError
+            await import_batch(batch)
+    finally:
+        await close_input()
+```
+
+### Rust
+
+```rust
+enum ImportError { Cancelled, Operation(Error) }
+
+fn import_rows(cancel: &AtomicBool) -> Result<(), ImportError> {
+    let _input = InputGuard::open().map_err(ImportError::Operation)?;
+    for batch in batches() {
+        if cancel.load(Ordering::Acquire) {
+            return Err(ImportError::Cancelled);
+        }
+        import_batch(batch).map_err(ImportError::Operation)?;
+    }
+    Ok(())
+}
+```
+
+## Boundaries and tensions
+
+A cancellation request does not give proof of rollback. Before cancellation occurs, an atomic or
+irreversible step can complete. Until the region has correct invariants, a small cleanup region can
+ignore the signal. Record each point. Do not discard a cancellation signal and return an incorrect
+success result.
+
+## Examples
+
+**Positive:** An import stops between committed batches, closes its input, records a resume token,
+and returns a clear cancellation result.
+
+**Misuse:** A canceled HTTP request has active database work and spawned subprocesses with no owner.
+
+**Athena/agent workflow:** A coordinator propagates an interrupted task to the subagents. The
+coordinator collects the terminal state of each subagent and records all completed side effects.
+
+## Related principles
+
+- [P033 State-Safe Failure Semantics](p033-state-safe-failure-semantics.md)
+- [P037 Idempotency Before Retry](p037-idempotency-before-retry.md)
+- [P046 Resumability](p046-resumability.md)
+- [P079 Explicit Ownership and Lifetimes](p079-explicit-ownership-and-lifetimes.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- No one primary source gives the general pattern. Do not record one language or framework as the
+  source.
+- [Go Concurrency Patterns: Context](https://go.dev/blog/context) records a 2014 model that
+  transmits deadlines and cancellation to request-scoped work.
+
+### Applicable information
+
+- [gRPC Cancellation](https://grpc.io/docs/guides/cancellation/) gives cancellation propagation.
+  Applications must stop work for a canceled RPC.
+- [Go: Canceling in-progress operations](https://go.dev/doc/database/cancel-operations) gives
+  a cancellation and cleanup example for database calls.
+
+### More information
+
+- [gRPC Deadlines](https://grpc.io/docs/guides/deadlines/) gives the relation between time bounds and
+  automatic cancellation. The guide gives the server application responsibility for spawned-work cleanup.
+
+[Back to the engineering principles catalog](../README.md#p082)

package/skills/_support/docs/principles/details/p083-irreversible-actions-last.md

@@ -0,0 +1,124 @@
+# P083 — Irreversible Actions Last
+
+## Definition
+
+**Irreversible Actions Last** completes validation, reversible preparation, authorization, and
+evidence collection before an irreversible external effect. A multistep workflow can have more than
+one irreversible step. Put each irreversible step near the end of the workflow.
+
+**Aliases:** none.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No source gives this text. The rule includes change control, transaction
+authorization, staged release, and rollback practice. The rule uses this order for software and agent
+workflows.
+
+## Decision rule
+
+Before an irreversible step, complete all checks and reversible preparation. Immediately before the
+specified operation, revalidate the mutable target and authority.
+
+## How to apply
+
+- Put steps in four groups: read-only, reversible, compensatable, and irreversible.
+- Validate inputs and targets first. Then prepare only reversible state.
+- With correct evidence, use previews, staging, backups, canaries, and dry runs.
+- Bind approval and authorization to the publication target and parameters.
+- After preparation, examine mutable facts again.
+- Where possible, make the commit step atomic or idempotent.
+- Record the outcome and all irreversible side effects.
+
+## Diagram
+
+Before the irreversible step, the workflow completes each reversible gate.
+
+```mermaid
+flowchart LR
+    A["Validate input"] --> B["Prepare reversible state"]
+    B --> C["Preview specified operation"]
+    C --> D["Revalidate target and authority"]
+    D --> E{"All checks satisfactory?"}
+    E -->|No| F["Stop without irreversible effect"]
+    E -->|Yes| G["Irreversible operation"]
+```
+
+## Language examples
+
+Immediately before publication, the two examples revalidate the artifact target.
+
+### Python
+
+```python
+def publish(request: Request) -> Receipt:
+    artifact = prepare(request)
+    preview(artifact)
+    verify_target(artifact.target)
+    verify_authority(request.actor, artifact.target)
+    return publisher.publish(artifact)
+```
+
+### Rust
+
+```rust
+fn publish(request: &Request) -> Result<Receipt, Error> {
+    let artifact = prepare(request)?;
+    preview(&artifact)?;
+    verify_target(&artifact.target)?;
+    verify_authority(&request.actor, &artifact.target)?;
+    publisher::publish(artifact)
+}
+```
+
+## Boundaries and tensions
+
+An irreversible operation can be the necessary result. The principle puts validation before the
+operation but does not prevent the operation. Long preparation can make decisions incorrect. The last
+gate examines mutable state again.
+
+Compensation is not a reversal. Messages, charges, deletions, and public releases can have
+external effects before compensation. Specified authorization is necessary for emergency paths.
+
+## Examples
+
+**Positive:** A release process assembles the artifact and does tests, staging, and target-revision
+verification. The release process receives bound authorization and then moves production traffic.
+
+**Misuse:** A checkout charges a payment method first. The checkout then validates inventory and delivery
+details. The workflow has the incorrect assumption that a refund removes all effects.
+
+**Athena/agent workflow:** An agent resolves the repository and issue body. The agent previews the
+specified request and does an authority verification. The agent then creates the public GitHub issue.
+
+## Related principles
+
+- [P021 Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md)
+- [P061 Separate Decision from High-Impact Execution](p061-separate-decision-from-high-impact-execution.md)
+- [P062 Human Approval for Irreversible or High-Risk Actions](p062-human-approval-for-irreversible-or-high-risk-actions.md)
+- [P076 Parse, Then Validate, Then Operate](p076-parse-then-validate-then-operate.md)
+- [P082 Design for Cancellation](p082-design-for-cancellation.md)
+
+## References
+
+### Source information
+
+- No one primary source gives the general order. Athena uses a synthesis of transaction,
+  change-control, and release-safety practice.
+
+### Applicable information
+
+- [OWASP Transaction Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html)
+  gives ordered state transitions and an authorization gate immediately before transaction
+  execution.
+- [Google SRE Workbook: Canarying Releases](https://sre.google/workbook/canarying-releases/)
+  gives information about staged exposure, evaluation, and rollback as release safety mechanisms.
+
+### More information
+
+- [NIST SP 800-53 Revision 5](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final) includes
+  configuration change control, impact analysis, authorization, testing, and documentation controls
+  for changes with governance.
+
+[Back to the engineering principles catalog](../README.md#p083)

package/skills/_support/docs/principles/details/p084-prefer-local-reasoning.md

@@ -0,0 +1,131 @@
+# P084 — Prefer Local Reasoning
+
+## Definition
+
+**Prefer Local Reasoning** makes a component clear from its contract, implementation, and local
+collaborators. The component has no nonlocal hidden state, implicit configuration, or implicit
+control flow. Its local contract identifies all necessary subsystem dependencies.
+
+**Aliases:** local reasoning and locality of reasoning.
+
+## Provenance
+
+**Classification:** principle with source evidence.
+
+No source records an initial author of the phrase. The rule uses modularity, information hiding,
+structured programs, and the Law of Demeter. These practices decrease the nonlocal knowledge
+necessary for a reader.
+
+## Decision rule
+
+Make each nonlocal correctness dependency explicit. When possible, move each invariant near the
+enforcement code. The local contract must give sufficient information without knowledge of the full
+system.
+
+## How to apply
+
+- Keep each invariant and the applicable state in the same module.
+- Use explicit narrow interfaces to supply important dependencies.
+- Use the minimum global state, hidden callbacks, reflection, and nonlocal effects.
+- Keep each state transition clear and near the operation that starts the transition.
+- Use types and contracts to show facts from a different component.
+- Give a clear entry point for lower-level implementation detail.
+
+## Diagram
+
+The local contract supplies each necessary fact to the component.
+
+```mermaid
+flowchart LR
+    A["Explicit inputs"] --> C["Local component"]
+    B["Dependency with a name"] --> C
+    C --> D["Clear result"]
+    E["Hidden global state"] -. "Do not use" .-> C
+```
+
+## Language examples
+
+The two examples accept ASCII-decimal cents to 1,000,000 and basis points to 10,000, with the same
+errors and integer half-up rule.
+
+### Python
+
+```python
+def parse_decimal(text: str, maximum: int, width: int) -> int:
+    if not text or len(text) > width or not text.isascii() or not text.isdecimal():
+        raise ValueError("invalid decimal value")
+    value = int(text)
+    if value > maximum:
+        raise ValueError("value outside specified range")
+    return value
+
+def total_cents(price: str, rate: str) -> int:
+    price_value = parse_decimal(price, 1_000_000, 7)
+    rate_value = parse_decimal(rate, 10_000, 5)
+    return price_value + (price_value * rate_value + 5_000) // 10_000
+```
+
+### Rust
+
+```rust
+fn total_cents(price: &str, rate: &str) -> Result<u64, &'static str> {
+    let parse = |text: &str, maximum, width| -> Result<u64, &'static str> {
+        if text.is_empty() || text.len() > width || !text.bytes().all(|b| b.is_ascii_digit()) {
+            return Err("invalid decimal value");
+        }
+        let value = text.parse::<u64>().map_err(|_| "invalid decimal value")?;
+        if value > maximum { return Err("value outside specified range"); }
+        Ok(value)
+    };
+    let (price, rate) = (parse(price, 1_000_000, 7)?, parse(rate, 10_000, 5)?);
+    Ok(price + (price * rate + 5_000) / 10_000)
+}
+```
+
+## Boundaries and tensions
+
+Local reasoning does not let components duplicate global policy or authoritative data. A component
+can use an explicit interface to access a canonical source. Authority, traces, and transactions can
+include more than one component. The architecture must show these control points and effects. Some
+distributed invariants are nonlocal. Record each nonlocal invariant.
+
+## Examples
+
+**Positive:** A pricing function receives a typed pricing policy and order. The function does not
+read mutable globals, environment variables, or an implicit request-local cache.
+
+**Misuse:** A property assignment starts an observer that the contract does not show. The
+observer in a different package mutates persistent state.
+
+**Athena/agent workflow:** An agent uses the task, repository instructions, and
+local implementation. The agent does not use memory about a different checkout without repository evidence.
+
+## Related principles
+
+- [P005 Modularity](p005-modularity.md)
+- [P018 Information Hiding](p018-information-hiding.md)
+- [P019 Explicit Contracts](p019-explicit-contracts.md)
+- [P078 Single Source of Truth](p078-single-source-of-truth.md)
+- [P085 Explicit Is Better Than Implicit](p085-explicit-is-better-than-implicit.md)
+
+## References
+
+### Source information
+
+- [Object-Oriented Programming: An Objective Sense of Style](https://doi.org/10.1145/62084.62113)
+  is the 1988 primary Law of Demeter paper. The paper gives the relation between a small quantity of
+  collaborator knowledge, less coupling, and clear correctness analysis.
+- [On the Criteria To Be Used in Decomposing Systems into Modules](https://doi.org/10.1145/361598.361623)
+  gives the information-hiding argument for clear module boundaries.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  gives this complexity rule. If readers cannot quickly know what code does, code has too much complexity.
+
+### More information
+
+- [Google Go Style Guide](https://google.github.io/styleguide/go/guide.html) uses clarity and reader
+  context for the selection of correct implementations.
+
+[Back to the engineering principles catalog](../README.md#p084)