@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/_support/docs/principles/details/p075-make-invalid-states-hard-to-represent.md

@@ -0,0 +1,128 @@
+# P075 — Make Invalid States Hard to Represent
+
+## Definition
+
+Use types, schemas, constructors, validation, encapsulation, and state machines to prevent invalid
+data combinations. Reject invalid data at the constructor boundary. As an alternative, make its
+representation unavailable to standard program paths. Core logic must receive values that satisfy
+important structural invariants.
+
+**Aliases:** make illegal states unrepresentable, encode invariants in the model.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+This rule has provenance in typed functional programs and domain models. This page does not name one
+author. Algebraic data types, abstract data types, design by contract, and schema
+validation supply established technical foundations.
+
+## Decision rule
+
+When a state combination is always invalid, use a construction that does not let standard callers
+make that combination. Only when the boundary or representation cannot enforce the invariant more
+clearly, use runtime checks at more than one location.
+
+## How to apply
+
+- When states are exclusive, replace correlated booleans and nullable fields with specified
+  variants.
+- Use validated constructors or factories that return a value that satisfies the invariant or a
+  specified error.
+- When unrestricted mutation can violate invariants, give field access only with operations that
+  enforce invariants.
+- Express units, identifiers, necessary fields, and legal transitions in types or schemas.
+- Revalidate facts from external mutable state at the responsible boundary.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A["Receive boundary data"] --> B["Parse specified state variant"]
+    B --> C["Apply constructor invariants"]
+    C --> D{"State valid?"}
+    D -- "No" --> E["Return specific error"]
+    D -- "Yes" --> F["Give valid value to core logic"]
+    F --> G["Use only legal transition"]
+```
+
+## Language examples
+
+The two examples represent exclusive payment states as variants with state-specific data.
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Pending:
+    request_id: str
+
+@dataclass(frozen=True)
+class Settled:
+    receipt_id: str
+
+Payment = Pending | Settled
+```
+
+```rust
+enum Payment {
+    Pending { request_id: String },
+    Settled { receipt_id: String },
+}
+```
+
+## Boundaries and tensions
+
+No type system can prove all temporal, distributed, authorization, or business invariants. External
+data is untrusted. Also use
+[P053 boundary validation](p053-validate-at-trust-boundaries.md) and
+[P076 parse-validate-operate](p076-parse-then-validate-then-operate.md). When the complexity of
+wrappers, generics, or type-level mechanisms is more than the risk reduction, do not use these
+mechanisms.
+Representations must be clear, easy to change, and compatible with necessary serialization
+contracts.
+
+## Examples
+
+**Positive:** One enum represents a payment state with variant-specific data.
+The payment cannot have the `settled` and `failed` states at the same time. The interface contains
+only legal transitions.
+
+**Misuse:** Three booleans and two nullable time stamps represent workflow state. Each caller must
+identify the invalid combinations. Each caller must reject them again.
+
+**Athena/agent workflow:** A constructor for a review contract must contain a revision, scope, and
+active principle content. Thus, the restricted reviewer cannot receive a contract with missing
+necessary data.
+
+## Related principles
+
+- [P019 Explicit Contracts](p019-explicit-contracts.md)
+- [P053 Validate at Trust Boundaries](p053-validate-at-trust-boundaries.md)
+- [P076 Parse, Then Validate, Then Operate](p076-parse-then-validate-then-operate.md)
+- [P079 Explicit Ownership and Lifetimes](p079-explicit-ownership-and-lifetimes.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+
+## References
+
+### Source information
+
+- [Liskov and Zilles, "Programming with Abstract Data Types" (1974)](https://doi.org/10.1145/800233.807045)
+  is a primary source for abstract types that control representation and operations.
+  The rule has no verified initial source.
+
+### Applicable information
+
+- [The Rust Programming Language: Defining an Enum](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html)
+  shows how variants and exhaustive matches let a compiler distinguish cases. The compiler can
+  verify that code handles all variants.
+- [Microsoft C#: Nullable reference types](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/null-safety/nullable-reference-types)
+  documents type annotations and flow analysis that find states that do not agree with declared null
+  contracts.
+
+### More information
+
+- [Meyer, "Applying Design by Contract"](https://www.kth.se/social/files/59526bfb56be5b4f17000807/meyer-92-contracts.pdf)
+  gives preconditions, postconditions, and invariants as runtime tools that enforce one contract.
+
+[Back to the engineering principles catalog](../README.md#p075)

package/skills/_support/docs/principles/details/p076-parse-then-validate-then-operate.md

@@ -0,0 +1,133 @@
+# P076 — Parse, Then Validate, Then Operate
+
+## Definition
+
+**Parse, Then Validate, Then Operate** is a boundary sequence. First, change an external
+representation into a specified internal structure. Then, validate the internal structure for syntax, meaning, security, and task
+limits. Operate only on the validated value. Core logic receives structured values and does not
+interpret the raw input again.
+
+**Aliases:** none. *Parse, Don't Validate* is a different rule.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+This sequence uses the *Parse, Don't Validate* type guidance. The two rules are not the same. The
+*Parse, Don't Validate* guidance uses types that cannot contain incorrect values. Athena
+includes validation because a parsed value can be incorrect for a domain rule, authority rule,
+invariant, or state precondition.
+
+## Decision rule
+
+Change boundary data to one canonical structure. Validate that structure fully. After the validator
+completes all input validation, the system can start a side effect.
+
+## How to apply
+
+- Find the trust boundary and the internal type for accepted data.
+- Parse the input. Reject it if it does not match a specified grammar or if its meaning is not clear.
+- Normalize only transformations with one specified meaning.
+- Validate ranges, relationships, invariants, authority, and state preconditions at operation time.
+- Make the operation accept only the validated structure.
+- Keep safe diagnostic context. Do not keep secrets or raw input that is not necessary.
+
+## Diagram
+
+The diagram shows one safe transition from raw data to an operation.
+
+```mermaid
+flowchart LR
+    A["Raw input"] --> B["One parse"]
+    B --> C["Structured value"]
+    C --> D["Validate all rules"]
+    D --> E{"Correct?"}
+    E -->|Yes| F["Operate"]
+    E -->|No| G["Reject before side effects"]
+```
+
+## Language examples
+
+Before the operation starts, each example validates the port.
+
+### Python
+
+```python
+def parse_port(text: str) -> int:
+    if not text.isascii() or not text.isdecimal():
+        raise ValueError("invalid port")
+    port = int(text)
+    if not 1 <= port <= 65_535:
+        raise ValueError("invalid port")
+    return port
+
+
+server.bind(parse_port(raw_port))
+```
+
+### Rust
+
+```rust
+fn parse_port(text: &str) -> Result<u16, String> {
+    if text.is_empty() || !text.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err("invalid port".into());
+    }
+    let port = text.parse::<u16>().map_err(|_| "invalid port")?;
+    if port == 0 {
+        return Err("invalid port".into());
+    }
+    Ok(port)
+}
+
+let port = parse_port(raw_port)?;
+server.bind(port)?;
+```
+
+## Boundaries and tensions
+
+Parsing is not sanitization. Validation is not authorization. Examine mutable facts again immediately
+before the operation. This check prevents time-of-check and time-of-use defects.
+
+Keep validation at the boundary. Validate a boundary value for each context after the boundary. Use types
+for stable invariants. Keep policy checks explicit.
+
+## Examples
+
+**Positive:** A boundary parser changes a deployment request into a typed target and version. A
+validator examines the permitted environment and the release state at validation time. The deployer receives only the
+validated request.
+
+**Misuse:** A parser returns an object with missing fields. The executor creates external resources.
+After the side effect, a check finds an incorrect field.
+
+**Athena/agent workflow:** An agent parses issue fields and file paths. The agent validates the
+fields and paths for compliance with the task and repository scope. The agent uses tools only with
+validated targets.
+
+## Related principles
+
+- [P053 Validate at Trust Boundaries](p053-validate-at-trust-boundaries.md)
+- [P059 Data Is Not Instruction](p059-data-is-not-instruction.md)
+- [P075 Make Invalid States Hard to Represent](p075-make-invalid-states-hard-to-represent.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- [Parse, Don't Validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/)
+  gives the type-oriented formulation. Types that cannot contain incorrect values give more information than Boolean checks.
+
+### Applicable information
+
+- [OWASP Input Validation Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)
+  gives the difference between syntactic and semantic validation. Before operation, the guidance tells
+  authors to validate untrusted data.
+
+### More information
+
+- [OWASP REST Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html)
+  gives guidance about secure parsers, strong input types, and content constraints. It tells
+  authors to reject input that is not in the API contract.
+
+[Back to the engineering principles catalog](../README.md#p076)

package/skills/_support/docs/principles/details/p077-separate-policy-from-mechanism.md

@@ -0,0 +1,112 @@
+# P077 — Separate Policy from Mechanism
+
+## Definition
+
+**Separate Policy from Mechanism** puts decisions about necessary behavior in policy. The principle
+puts execution capabilities in mechanisms. A mechanism supplies stable capabilities. A policy selects
+and controls those capabilities for a specified context.
+
+**Aliases:** policy-mechanism separation and separation of policy and mechanism.
+
+## Provenance
+
+**Classification:** principle with source evidence.
+
+Operating-system research used this distinction. The Hydra system put policy and mechanism in
+different components for schedules, memory pages, and protection. The Hydra mechanisms let external
+policies change. The principle is also applicable to applications, security, work control, storage, and
+infrastructure.
+
+## Decision rule
+
+Give a policy boundary with a name to a rule that can change. Keep a neutral mechanism that uses each
+selected policy correctly.
+
+## How to apply
+
+- Find decisions that can change. Put these decisions in policy interfaces.
+- Give policy inputs, outputs, defaults, and failure behavior an explicit contract.
+- Use a narrow interface to supply the policy. Do not put copies of policy branches in the mechanism.
+- Do policy-selection tests and mechanism-correctness tests independently.
+- If a policy is a security or integrity control, keep enforcement mandatory.
+
+## Diagram
+
+The policy selects an operation. The mechanism does only the selected operation.
+
+```mermaid
+flowchart LR
+    A["Context"] --> B["Policy decision"]
+    B --> C["Selected operation"]
+    C --> D["Neutral mechanism"]
+    D --> E["Result"]
+```
+
+## Language examples
+
+The two examples supply a policy to a stable queue mechanism.
+
+### Python
+
+```python
+def dispatch(job, priority_policy, queue) -> None:
+    priority = priority_policy(job)
+    entry = QueueEntry(job, priority)
+    queue.push(entry)
+```
+
+### Rust
+
+```rust
+fn dispatch<P: PriorityPolicy>(job: Job, policy: &P, queue: &mut Queue) {
+    let priority = policy.priority(&job);
+    let entry = QueueEntry::new(job, priority);
+    queue.push(entry);
+}
+```
+
+## Boundaries and tensions
+
+An abstraction is not necessary for each condition. Until two components use a stable policy, the
+policy can stay local. A neutral mechanism must use the policy.
+
+Some low-level policy is necessary for fairness, safety, or resource limits. Record that decision.
+
+## Examples
+
+**Positive:** A scheduler supplies queueing and dispatch primitives while a different strategy
+selects priority and fairness rules.
+
+**Misuse:** Authorization rules occur in transport handlers, database helpers, and user interfaces.
+One role change causes edits to all three, and the edits do not agree.
+
+**Athena/agent workflow:** A coordinator selects tasks that can operate independently in parallel. The
+delegation mechanism starts, monitors, and collects workers without new scope policy.
+
+## Related principles
+
+- [P016 Separation of Concerns](p016-separation-of-concerns.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)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+
+## References
+
+### Source information
+
+- [Policy/mechanism separation in Hydra](https://doi.org/10.1145/1067629.806531)
+  is the 1975 primary paper that gives the principle for schedules, memory pages, and protection.
+
+### Applicable information
+
+- [Linux Integrity Policy Enforcement](https://www.kernel.org/doc/html/latest/security/ipe.html)
+  gives a kernel design with integrity measurement and local enforcement policies in different
+  components.
+
+### More information
+
+- [The Protection of Information in Computer Systems](https://www.cs.virginia.edu/~evans/cs551/saltzer/)
+  gives guidance on Complete Mediation, least privilege, and simple security mechanisms.
+
+[Back to the engineering principles catalog](../README.md#p077)

package/skills/_support/docs/principles/details/p078-single-source-of-truth.md

@@ -0,0 +1,131 @@
+# P078 — Single Source of Truth
+
+## Definition
+
+**Single Source of Truth** (SSOT) gives each authoritative mutable fact or policy one declared owner
+and one write path. Other representations are derived views, caches, replicas, or exports. The
+source and synchronization rules for each representation are explicit.
+
+**Aliases:** SSOT, authoritative source, canonical owner.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+The phrase occurs in data, configuration, and software design. No source records where the phrase
+first occurred. The rule uses concepts from database normalization and DRY. The rule is only about
+authority and divergence, not all duplication.
+
+## Decision rule
+
+For each mutable fact, record the authoritative representation and the permitted writers. Record how
+all other representations receive the same data from the authoritative representation.
+
+## How to apply
+
+- Give each domain fact an authoritative owner and specified write interface.
+- If policy accepts the cost, make secondary representations from authoritative data.
+- Give caches and replicas a non-authoritative status. Record freshness limits.
+- Record the source, version, and reconciliation rules for asynchronous boundaries.
+- Use an explicit operation to move authority. Do not let two writers give different values without a signal.
+- When authors can change copies independently, find differences.
+
+## Diagram
+
+The authoritative source supplies each derived representation.
+
+```mermaid
+flowchart LR
+    A["Permitted writer"] --> B["Authoritative source"]
+    B --> C["Read-only derived view"]
+    B --> D["Cache"]
+    B --> E["Replica"]
+```
+
+## Language examples
+
+The two examples derive one timeout from the authoritative configuration and reject values that are
+not in the `u64` domain.
+
+### Python
+
+```python
+@dataclass(frozen=True)
+class Config:
+    timeout_seconds: str
+
+def client_timeout(config: Config) -> int:
+    text = config.timeout_seconds
+    if not text.isascii() or not text.isdecimal():
+        raise ValueError("timeout must be a u64")
+    seconds = int(text)
+    if seconds > 2**64 - 1:
+        raise ValueError("timeout must be a u64")
+    return seconds
+```
+
+### Rust
+
+```rust
+struct Config {
+    timeout_seconds: String,
+}
+
+fn client_timeout(config: &Config) -> Result<u64, &'static str> {
+    let text = &config.timeout_seconds;
+    if text.is_empty() || !text.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err("timeout must be a u64");
+    }
+    text.parse::<u64>().map_err(|_| "timeout must be a u64")
+}
+```
+
+## Boundaries and tensions
+
+SSOT is not a rule for one database, one service, or one global system owner. Different bounded contexts
+can own different facts. Distributed replicas can increase availability. When the authority and
+consistency model of each copy are clear, derived copies are permitted in the specified model.
+When control causes a bottleneck or incorrect agreement, central control is incorrect.
+
+## Examples
+
+**Positive:** One schema owns an API shape. Generated clients and documentation show the schema
+version. Authors do not change derived artifacts independently.
+
+**Misuse:** Code, deployment configuration, and a runbook give timeout defaults that authors can
+change independently. No precedence rule selects one of the different values.
+
+**Athena/agent workflow:** The principles catalog owns IDs and decision rules. Detail pages give more
+information. Skills refer to the catalog and do not keep duplicate definitions.
+
+## Related principles
+
+- [P018 Information Hiding](p018-information-hiding.md)
+- [P020 Executable Architecture](p020-executable-architecture.md)
+- [P077 Separate Policy from Mechanism](p077-separate-policy-from-mechanism.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+- [P089 Delete Obsolete Configuration and Dependencies](p089-delete-obsolete-configuration-and-dependencies.md)
+
+## References
+
+### Source information
+
+- No primary source records the first occurrence of the phrase. Use the phrase as a practitioner term without
+  attribution to one author.
+- [On the Criteria To Be Used in Decomposing Systems into Modules](https://doi.org/10.1145/361598.361623)
+  gives a historical foundation for authoritative module boundaries.
+
+### Applicable information
+
+- [Microsoft Azure Architecture Center: Data considerations for microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/design/data-considerations)
+  tells architects to use one authoritative service for necessary strong consistency. The guidance
+  lets a system use non-authoritative copies with explicit eventual consistency.
+
+### More information
+
+- [NASA: A PPE Use Case on Configuration Management Approach for MBSE](https://ntrs.nasa.gov/citations/20230000079)
+  gives a model that is the controlled source for derived engineering artifacts.
+- [USENIX SREcon: There Is No Single Source of Truth](https://www.usenix.org/conference/srecon24emea/presentation/burke)
+  gives information about ambiguity and authority for each domain in production systems.
+
+[Back to the engineering principles catalog](../README.md#p078)

package/skills/_support/docs/principles/details/p079-explicit-ownership-and-lifetimes.md

@@ -0,0 +1,124 @@
+# P079 — Explicit Ownership and Lifetimes
+
+## Definition
+
+**Explicit Ownership and Lifetimes** gives each resource and work unit a clear owner and a specified
+lifetime. The principle also gives transfer, cleanup, and termination rules. Resources include memory,
+files, locks, transactions, connections, callbacks, processes, tasks, and temporary artifacts.
+
+**Aliases:** none. Resource Acquisition Is Initialization (RAII) and ownership types are
+implementation families for this principle.
+
+## Provenance
+
+**Classification:** principle with source evidence.
+
+No source records an initial author of the general rule. Structured programs, C++ RAII, ownership
+types, scope cleanup, and structured concurrency use this rule. These mechanisms are different.
+Each mechanism makes responsibility and lifetime clear.
+
+## Decision rule
+
+Before resource acquisition, record the resource owner and lifetime. Record each ownership
+transfer. Give cleanup rules for success, failure, timeout, and cancellation.
+
+## How to apply
+
+- Use scope-bound resource handles, context managers, or equivalent cleanup constructs.
+- Make ownership transfer clear in types, names, or interface contracts.
+- If no durable owner accepts ownership, connect child tasks to a parent scope.
+- Give the shutdown order and wait behavior for concurrent work.
+- Until the owner records the terminal disposition of each item, record temporary artifacts and state.
+- Do tests of failure exits and the standard release path.
+
+## Diagram
+
+The owner controls the resource for the full resource lifetime.
+
+```mermaid
+flowchart LR
+    A["Acquire resource"] --> B["Owner with a name"]
+    B --> C{"Transfer?"}
+    C -->|Yes| D["Specified new owner"]
+    C -->|No| E["Owner does not change"]
+    D --> F["Cleanup on all exits"]
+    E --> F
+```
+
+## Language examples
+
+The two examples connect file cleanup to a clear scope, accept line-feed (LF) and
+carriage-return/line-feed (CRLF) endings, and give an error for an empty file.
+
+### Python
+
+```python
+def first_line(path: Path) -> str:
+    with path.open("rb") as stream:
+        line = stream.readline()
+    if line == b"":
+        raise EOFError("empty file")
+    if line.endswith(b"\r\n"):
+        line = line[:-2]
+    elif line.endswith(b"\n"):
+        line = line[:-1]
+    return line.decode("utf-8")
+```
+
+### Rust
+
+```rust
+fn first_line(path: &Path) -> io::Result<String> {
+    let file = File::open(path)?;
+    let mut lines = BufReader::new(file).lines();
+    lines.next().transpose()?.ok_or_else(|| io::ErrorKind::UnexpectedEof.into())
+}
+```
+
+## Boundaries and tensions
+
+Garbage collection does not close files, release locks, cancel requests, or complete transactions.
+Shared ownership and long work can follow the principle. The last owner of each resource and the
+shutdown protocol must stay explicit. A lifetime does not have to be the same as a lexical scope.
+Leases and durable workflows can have longer lifetimes.
+
+## Examples
+
+**Positive:** A transaction object owns the lock and connection. The object does one commit or rollback
+and releases each resource on all exit paths.
+
+**Misuse:** A helper starts a detached task. After the request stops, the task uses a request-scoped
+credential. The task has no cancellation contract or supervisor.
+
+**Athena/agent workflow:** A coordinator records each subagent, the subagent deadline, the specified
+output, and the terminal disposition. The coordinator collects or cancels all children. The
+coordinator then records completion.
+
+## Related principles
+
+- [P039 Bounded Waiting](p039-bounded-waiting.md)
+- [P046 Resumability](p046-resumability.md)
+- [P080 Make Concurrency Deliberate](p080-make-concurrency-deliberate.md)
+- [P082 Design for Cancellation](p082-design-for-cancellation.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- [Bjarne Stroustrup's C++ glossary](https://stroustrup.com/glossary.html) records RAII as a
+  method that binds resource management to object construction and destruction.
+
+### Applicable information
+
+- [The Rust Programming Language: What Is Ownership?](https://doc.rust-lang.org/stable/book/ch04-01-what-is-ownership.html)
+  gives compiler-enforced ownership and scope rules.
+- [Go: Contexts and structs](https://go.dev/blog/context-and-structs) gives information about a clear
+  request lifetime at each call. This per-call lifetime makes cancellation and deadlines clear.
+
+### More information
+
+- [Standard C++ FAQ: Exceptions and RAII](https://isocpp.org/wiki/faq/exceptions/1000) gives
+  information about deterministic cleanup for success and exception paths.
+
+[Back to the engineering principles catalog](../README.md#p079)