@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/_support/docs/principles/details/p085-explicit-is-better-than-implicit.md

@@ -0,0 +1,123 @@
+# P085 — Explicit Is Better Than Implicit
+
+## Definition
+
+**Explicit Is Better Than Implicit** makes important behavior clear in interfaces, types,
+configuration, and local control flow. This behavior has an effect on correctness, security, or
+maintenance. Hidden conventions must not set dependencies, defaults, conversions, state changes,
+ownership, or side effects.
+
+**Aliases:** explicitness principle and explicit over implicit.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Tim Peters wrote the aphorism in a 1999 Python community post. PEP 20 then recorded the aphorism.
+Other interface and language design guidance uses the same rule. Athena uses the rule for all
+languages.
+
+## Decision rule
+
+If a fact changes an operation, show that fact at the selection or call point.
+
+## How to apply
+
+- Use specified interfaces to supply dependencies and request context.
+- Give clear names to data-loss conversions, defaults, units, and fallback behavior.
+- Use explicit state transitions and terminal states.
+- Show external writes and transaction commits in control flow.
+- Record configuration precedence and the source of each selected value.
+- Use schemas and typed values. Do not use magic strings or positional conventions.
+
+## Diagram
+
+The call site supplies each fact that can change the result.
+
+```mermaid
+flowchart LR
+    A["Dependency with a name"] --> D["Operation"]
+    B["Explicit option"] --> D
+    C["Declared default"] --> D
+    D --> E["Clear result"]
+```
+
+## Language examples
+
+The two examples accept the same wall-time and zone inputs, and return different errors for ambiguous
+and nonexistent source times.
+
+### Python
+
+```python
+def convert_time(local: datetime, source: ZoneInfo, target: ZoneInfo) -> datetime:
+    if local.tzinfo is not None:
+        raise ValueError("expected local wall time")
+    candidates = [local.replace(tzinfo=source, fold=fold) for fold in (0, 1)]
+    valid = [value for value in candidates if value.astimezone(timezone.utc)
+             .astimezone(source).replace(tzinfo=None) == local]
+    instants = {value.astimezone(timezone.utc) for value in valid}
+    if not instants:
+        raise ValueError("nonexistent local time")
+    if len(instants) > 1:
+        raise ValueError("ambiguous local time")
+    return instants.pop().astimezone(target)
+```
+
+### Rust
+
+```rust
+fn convert_time(local: NaiveDateTime, source: Tz, target: Tz)
+    -> Result<DateTime<Tz>, &'static str> {
+    match source.from_local_datetime(&local) {
+        LocalResult::Single(value) => Ok(value.with_timezone(&target)),
+        LocalResult::Ambiguous(_, _) => Err("ambiguous local time"),
+        LocalResult::None => Err("nonexistent local time"),
+    }
+}
+```
+
+## Boundaries and tensions
+
+A large quantity of text is not necessary for explicitness. A stable language construct or known repository
+convention can show the contract. Information hiding stays necessary. Show the contract, not each
+internal detail. Do not make each implementation decision public configuration. Public configuration
+increases the interface surface and complexity.
+
+## Examples
+
+**Positive:** A timestamp conversion shows the source and destination time zones. The conversion does
+not use the process locale.
+
+**Misuse:** A hidden thread-local flag controls how a save method publishes an external event.
+
+**Athena/agent workflow:** An agent records assumptions, validation limits, and public
+operations. Repository content does not give authority to the agent.
+
+## Related principles
+
+- [P006 Principle of Least Astonishment](p006-principle-of-least-astonishment.md)
+- [P018 Information Hiding](p018-information-hiding.md)
+- [P019 Explicit Contracts](p019-explicit-contracts.md)
+- [P076 Parse, Then Validate, Then Operate](p076-parse-then-validate-then-operate.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+
+## References
+
+### Source information
+
+- [PEP 20 — The Zen of Python](https://peps.python.org/pep-0020/) is the primary published source
+  for the aphorism and records the initial Python-list history of the aphorism.
+
+### Applicable information
+
+- [Google Go Style Guide](https://google.github.io/styleguide/go/guide.html) tells authors to make
+  clarity, consistency, and reader context most important. The guide does not make short text most important.
+
+### More information
+
+- [Design by Contract](https://www.kth.se/social/files/59526bfb56be5b4f17000807/meyer-92-contracts.pdf)
+  gives information about explicit preconditions, postconditions, and invariants. Explicit contracts
+  make component obligations clear for checks.
+
+[Back to the engineering principles catalog](../README.md#p085)

package/skills/_support/docs/principles/details/p086-readability-counts.md

@@ -0,0 +1,113 @@
+# P086 — Readability Counts
+
+## Definition
+
+**Readability Counts** makes code clear for the personnel who examine, debug, operate, and change it.
+Clear names, linear control flow, one-function units, and clear data forms help correctness and
+maintenance. Readability is a maintenance property.
+
+**Aliases:** code readability and readable-code principle.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+The aphorism occurs in Tim Peters's Zen of Python, which PEP 20 records. Before PEP 20, readability
+was important. Readability is applicable to all languages. Personnel read and change software many
+times after the first software version.
+
+## Decision rule
+
+For correct designs, select the design with the most clear function, control flow, data meaning, and
+failure behavior.
+
+## How to apply
+
+- Use domain names that give role and units.
+- Give each function or module one behavior.
+- Use linear control flow and results with names between operations. Do not compress control flow.
+- Make invariants and failure branches easy to find.
+- Follow specified formatting and language idioms.
+- Examine code in its local context, not only as an isolated diff.
+
+## Diagram
+
+The reader follows one linear control flow with decisions that have names.
+
+```mermaid
+flowchart LR
+    A["Clear inputs"] --> B["Condition with a name"]
+    B -->|Yes| C["Operation with a name"]
+    B -->|No| D["Clear failure"]
+    C --> E["Clear result"]
+```
+
+## Language examples
+
+The two examples use predicates with names that give the eligibility rules.
+
+### Python
+
+```python
+def is_eligible(user: User) -> bool:
+    has_verified_email = user.email_verified
+    is_active = user.status is Status.ACTIVE
+    return has_verified_email and is_active
+```
+
+### Rust
+
+```rust
+fn is_eligible(user: &User) -> bool {
+    let has_verified_email = user.email_verified;
+    let is_active = user.status == Status::Active;
+    has_verified_email && is_active
+}
+```
+
+## Boundaries and tensions
+
+Readability changes with the audience and system conventions. A long replacement for standard code
+can decrease readability. Do not remove necessary abstractions or duplicate knowledge to
+keep all code in one file. Code with much complexity can be necessary for performance, security, and
+interoperability. Isolate that code and do tests. Record each limit that the code does not show.
+
+## Examples
+
+**Positive:** Predicates with names give a compound eligibility check. The predicates contain the domain
+rules and give the rule that caused the failure.
+
+**Misuse:** A short expression removes four lines but mixes conversion, validation, mutation, and
+fallback behavior in one statement.
+
+**Athena/agent workflow:** An agent gives a diff for the task scope only and an evidence
+summary. A reviewer can examine what the change does without the full session transcript.
+
+## Related principles
+
+- [P001 KISS](p001-kiss.md)
+- [P006 Principle of Least Astonishment](p006-principle-of-least-astonishment.md)
+- [P071 Consistency Over Personal Preference](p071-consistency-over-personal-preference.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+- [P087 Comments Explain Why, Code Explains What](p087-comments-explain-why-code-explains-what.md)
+
+## References
+
+### Source information
+
+- [PEP 20 — The Zen of Python](https://peps.python.org/pep-0020/) is the primary published source
+  for the phrase *Readability counts*.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  examines naming, complexity, comments, and context. The guidance also has a check of reader
+  comprehension.
+
+### More information
+
+- [Software Engineering at Google: Style Guides and Rules](https://abseil.io/resources/swe-book/html/ch08.html)
+  gives code standards for large projects. The standards use reader clarity and consistency, not
+  one person's preference.
+
+[Back to the engineering principles catalog](../README.md#p086)

package/skills/_support/docs/principles/details/p087-comments-explain-why-code-explains-what.md

@@ -0,0 +1,120 @@
+# P087 — Comments Explain Why, Code Explains What
+
+## Definition
+
+**Comments Explain Why, Code Explains What** uses code to show its standard operation. Comments give
+rationale, limits, invariants, sources, unusual tradeoffs, or context that code cannot show.
+Public interface documentation independently gives function, operation, behavior, parameters, results,
+and failures.
+
+**Aliases:** why-comments and rationale comments.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+No source records an initial author of the phrase. The phrase is a code-review heuristic. Google's
+published review guidance gives the same default and important exceptions.
+
+## Decision rule
+
+First, use names, structure, and types to make the code clear. When code cannot show important
+rationale, add a comment. Also record each necessary public contract.
+
+## How to apply
+
+- Record the rationale for a workaround, invariant, limit, or compatibility path.
+- When one source controls an unusual decision, refer to the applicable specification, issue, or measurement.
+- Follow the language and repository contract for public API documentation.
+- Keep comments adjacent to the applicable behavior.
+- Change or remove comments in the same change that makes the comments incorrect.
+- Delete each expired TODO or replace the TODO with specified work that has an owner.
+
+## Diagram
+
+The code shows the operation. The comment supplies rationale that the code cannot show.
+
+```mermaid
+flowchart LR
+    A["Clear code"] --> B["Clear operation"]
+    C["Necessary comment"] --> D["Rationale or invariant"]
+    B --> E["Clear context"]
+    D --> E
+```
+
+## Language examples
+
+The two examples use a comment only because of the external compatibility contract.
+
+### Python
+
+```python
+def decode(message: Message) -> Payload:
+    # Keep version 1 until contract ACME-42 expires in 2027.
+    if message.version == 1:
+        return decode_legacy(message)
+    return decode_current(message)
+```
+
+### Rust
+
+```rust
+fn decode(message: &Message) -> Payload {
+    // Keep version 1 until contract ACME-42 expires in 2027.
+    match message.version {
+        1 => decode_legacy(message),
+        _ => decode_current(message),
+    }
+}
+```
+
+## Boundaries and tensions
+
+Comments can be necessary for algorithms with much complexity, regular expressions, protocols, and performance
+code. Comments can give information about the algorithm steps. Some rationale and algorithm meaning
+cannot be clear in executable notation. When the implementation is clear, interface documentation must include external behavior.
+Comments do not make control flow with much complexity correct. Comments must not show secrets or
+give code facts again because the facts can change.
+
+## Examples
+
+**Positive:** A comment refers to the legacy format. Removal must wait for the migration milestone
+with a specified name.
+
+**Misuse:** A comment gives "increment retry count" immediately above a clear increment. The comment
+does not give the specified retry limit.
+
+**Athena/agent workflow:** A repository helper uses a comment to record why the helper sets an audit limit. The
+comment keeps the policy rationale without a prose validator.
+
+## Related principles
+
+- [P018 Information Hiding](p018-information-hiding.md)
+- [P019 Explicit Contracts](p019-explicit-contracts.md)
+- [P047 Observability Is Part of Correctness](p047-observability-is-part-of-correctness.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+- [P086 Readability Counts](p086-readability-counts.md)
+
+## References
+
+### Source information
+
+- No primary source records one coinage. Readers must use the phrase as a practitioner
+  heuristic, not as a quotation from one author.
+
+### 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 the rule that comments usually give rationale. The guidance gives algorithms with much complexity and
+  regular expressions as examples where information about the operation can help.
+- [Google API reference code comments](https://developers.google.com/style/api-reference-comments)
+  gives public API documentation rules. Public API documentation must include function, operation,
+  parameters, results, and exceptions.
+
+### More information
+
+- [Google Documentation Best Practices](https://google.github.io/styleguide/docguide/best_practices.html)
+  gives information about the differences between inline comments, API documentation, READMEs, and
+  documents about concepts. Audience and function control the differences.
+
+[Back to the engineering principles catalog](../README.md#p087)

package/skills/_support/docs/principles/details/p088-delete-dead-code.md

@@ -0,0 +1,125 @@
+# P088 — Delete Dead Code
+
+## Definition
+
+**Delete Dead Code** removes code that is unreachable, superseded, commented-out, obsolete, or without a consumer. First,
+do a verification that no necessary consumer or contract uses the code. Version control keeps history.
+Alternatives without a consumer increase maintenance cost and inspection load.
+
+**Aliases:** dead-code removal and obsolete-code cleanup.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+No source records an initial author of the rule. Compilers remove dead code during optimization.
+Maintainers also remove reachable source that has no product function. Athena removes code only
+after an inspection finds no product function.
+
+## Decision rule
+
+Remove code that has no necessary consumer in runtime, build, test, migration, compatibility, or
+documentation. After the removal, do tests of behavior. Do not keep a code copy without a specified
+consumer.
+
+## How to apply
+
+- Examine direct and indirect call sites, entry points, registrations, and generated references.
+- Examine reflection, dynamic loading, feature flags, serialization, and external API compatibility.
+- Examine history and tests for the code rationale.
+- Delete tests and documentation for the obsolete behavior only.
+- Keep the removal in one specified scope.
+- Do the repository's applicable static, behavioral, packaging, and integration checks.
+
+## Diagram
+
+After an inspection finds zero necessary consumers, the deletion starts.
+
+```mermaid
+flowchart LR
+    A["Candidate dead code"] --> B["Examine all consumers"]
+    B --> C{"Necessary consumer?"}
+    C -->|Yes| D["Keep or migrate"]
+    C -->|No| E["Delete all obsolete code"]
+    E --> F["Do behavior tests"]
+```
+
+## Language examples
+
+After removal of an obsolete fallback, the two examples show the remaining path.
+
+### Python
+
+```python
+class Command(Enum):
+    SERVE = "serve"
+
+def dispatch(command: Command) -> None:
+    match command:
+        case Command.SERVE:
+            serve()
+```
+
+### Rust
+
+```rust
+enum Command {
+    Serve,
+}
+
+fn dispatch(command: Command) {
+    match command {
+        Command::Serve => serve(),
+    }
+}
+```
+
+## Boundaries and tensions
+
+A local inspection does not give proof that a public interface or plug-in hook has no consumer. A removal can make
+deprecation and migration necessary. If historical rationale controls code at this time, the rationale is active.
+Change the canonical input to remove generated source. Do not edit the generated output independently. Scope
+fidelity limits cleanup to the specified scope.
+
+## Examples
+
+**Positive:** A maintainer removes a command with no external compatibility obligation. The
+maintainer removes the handler, registration, tests, and help for the command. The maintainer then
+makes the package again.
+
+**Misuse:** A reviewer deletes a callback with no clear caller. The reviewer does not examine the
+configuration name. A framework uses that name to load the callback.
+
+**Athena/agent workflow:** An agent first does verification of manifests, references, tests, and
+repository history. After this inspection, the agent removes the helper. Text inspection is not
+sufficient proof.
+
+## Related principles
+
+- [P007 Subtraction Over Addition](p007-subtraction-over-addition.md)
+- [P008 Understand Before Subtracting](p008-understand-before-subtracting.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+- [P089 Delete Obsolete Configuration and Dependencies](p089-delete-obsolete-configuration-and-dependencies.md)
+
+## References
+
+### Source information
+
+- No primary source records one coinage. The source-level rule changes compiler dead-code
+  elimination into a maintenance rule.
+
+### Applicable information
+
+- [Google SRE: Operational Simplicity](https://sre.google/sre-book/simplicity/) gives usual
+  dead-code removal as a practice. Code for operations must have a necessary function.
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  gives reviewers a check of comments and TODOs in the change. A change can make comments and TODOs obsolete.
+
+### More information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  gives information about self-contained deletions and small changes. Small self-contained changes
+  make inspection and reversal easy.
+
+[Back to the engineering principles catalog](../README.md#p088)

package/skills/_support/docs/principles/details/p089-delete-obsolete-configuration-and-dependencies.md

@@ -0,0 +1,125 @@
+# P089 — Delete Obsolete Configuration and Dependencies
+
+## Definition
+
+**Delete Obsolete Configuration and Dependencies** completes a removal in all parts of its support
+surface. First, do a verification that the consumer count is zero. Then, remove obsolete flags,
+packages, lockfile entries, deployment settings, tests, documents, metrics, and support code.
+
+**Aliases:** none.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No one source gives this rule. The rule includes dependency hygiene, configuration control,
+attack-surface reduction, and evidence from operations. If the maintainer does not complete a
+removal, the removal can cause incorrect artifacts or artifacts with vulnerabilities.
+
+## Decision rule
+
+After the workflow keeps each necessary support artifact, remove each obsolete artifact with its
+canonical control. Then, complete the removal.
+
+## How to apply
+
+- Trace the removed capability in manifests, lockfiles, images, deploy files, and environment
+  variables.
+- Examine optional and build-time consumers. Examine consumers in dependency chains, platforms, and runtime loaders.
+- Remove obsolete feature flags, defaults, secrets, dashboards, alerts, and runbook steps.
+- Change the canonical dependency or configuration source, then make the derived artifacts again.
+- Do tests of clean installation, packaging, startup, specified platforms, and deployment paths.
+- Examine the dependency and configuration diff for upgrades or drift that are not in the specified change.
+
+## Diagram
+
+The removal follows each support artifact to the last consumer that inspection finds.
+
+```mermaid
+flowchart LR
+    A["Retired capability"] --> B["Trace support surface"]
+    B --> C{"Remaining consumer?"}
+    C -->|Yes| D["Keep necessary artifact"]
+    C -->|No| E["Remove canonical input"]
+    E --> F["Update derived state"]
+    F --> G["Clean install and package tests"]
+```
+
+## Language examples
+
+The two examples use only the remaining encoder after removal of the obsolete dependency.
+
+### Python
+
+```python
+from current_encoder import encode
+
+def export(data: Record) -> bytes:
+    payload = encode(data)
+    return payload
+```
+
+### Rust
+
+```rust
+use current_encoder::encode;
+
+fn export(data: &Record) -> Vec<u8> {
+    encode(data)
+}
+```
+
+## Boundaries and tensions
+
+Configuration and packages can have external, migration, or platform consumers. Other systems can
+also have consumers. A local inspection can give a result that does not include these consumers.
+
+Obey compatibility and deprecation contracts. Do not add a
+dependency update that is not in the specified cleanup. Keep lockfile integrity and
+supply-chain evidence. A period with no alert does not give sufficient evidence to remove a safety control.
+
+## Examples
+
+**Positive:** Removal of an obsolete exporter also removes its package, lockfile closure, feature
+flag, credentials, container layer, metrics, tests, and operator documentation.
+
+**Misuse:** Production code no longer reads a flag. Deployment templates continue to show the
+flag, and each release image contains the parser dependency with no consumer.
+
+**Athena/agent workflow:** An agent that removes a skill helper also does verification of package
+inclusion, references, tests, and shipped documentation. The agent does not delete only the script.
+
+## Related principles
+
+- [P008 Understand Before Subtracting](p008-understand-before-subtracting.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P055 Minimize Attack Surface](p055-minimize-attack-surface.md)
+- [P057 Supply-Chain Integrity](p057-supply-chain-integrity.md)
+- [P078 Single Source of Truth](p078-single-source-of-truth.md)
+- [P088 Delete Dead Code](p088-delete-dead-code.md)
+
+## References
+
+### Source information
+
+- No primary source gives this synthesis. Athena records the rule as a lifecycle and supply-chain
+  synthesis and does not give one author as the source.
+
+### Applicable information
+
+- [OpenSSF: Simplifying Software Component Updates](https://best.openssf.org/Simplifying-Software-Component-Updates)
+  gives information about dependency cost, removal of components that are not necessary, lockfiles,
+  and automated verification.
+- [NIST SP 800-218, Secure Software Development Framework 1.1](https://csrc.nist.gov/pubs/sp/800/218/final)
+  gives applicable practices for protection and maintenance of software components and build inputs.
+
+### More information
+
+- [CISA: Secure by Design and Default](https://www.cisa.gov/sites/default/files/2023-06/principles_approaches_for_security-by-design-default_508c.pdf)
+  tells developers to use protection mechanisms and remove features that are not necessary. Features that
+  are not necessary increase the attack surface.
+- [Google SRE: Regaining Simplicity](https://sre.google/workbook/simplicity/) gives information about
+  removal of dependencies with no consumer, configuration, and operation complexity. Personnel have
+  responsibility for this engineering work.
+
+[Back to the engineering principles catalog](../README.md#p089)