@homericintelligence/athena-opencode 0.5.0 → 0.5.1

package/skills/_support/docs/principles/details/p007-subtraction-over-addition.md

@@ -0,0 +1,113 @@
+# P007 — Subtraction Over Addition
+
+## Definition
+
+For **Subtraction Over Addition**, an author must examine removal, consolidation, or reuse
+before an addition. Possible additions include code, state, dependencies, configuration, services, and
+processes. When a current mechanism obeys the requirement, select that mechanism.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Athena gives this name to an idea from empirical research and established simplicity heuristics. Adams et al.
+found that persons frequently do not examine subtractive changes that have value. The result
+gives evidence for an explicit subtraction prompt. The research does not show that subtraction is always
+the correct engineering decision.
+
+## Decision rule
+
+Before you add a component, examine all applicable subtractive or reuse alternatives. When an
+alternative keeps necessary behavior, safety, clarity, and compatibility, select that alternative.
+
+## How to apply
+
+- Write the outcome without the proposed new mechanism.
+- Find obsolete branches, redundant state, duplicate authorities, and current capabilities.
+- Compare lifecycle, failure, security, and operation costs, not only implementation work.
+- Before removal, record consumers and contracts.
+- Only when the artifacts are not necessary for current product behavior, delete related tests or
+  documentation.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Write the necessary outcome"] --> B["Find removal, consolidation, and reuse alternatives"]
+    B --> C{"Does an alternative keep all contracts?"}
+    C -->|No| D["Add the necessary mechanism"]
+    C -->|Yes| E["Select the subtractive alternative"]
+    D --> F["Record total system cost"]
+    E --> F
+```
+
+## Language examples
+
+The two examples derive the count from records and do not use duplicate state.
+
+```python
+def active_count(users: list[User]) -> int:
+    count = 0
+    for user in users:
+        count += int(user.active)
+    return count
+```
+
+```rust
+fn active_count(users: &[User]) -> usize {
+    users
+        .iter()
+        .filter(|user| user.active)
+        .count()
+}
+```
+
+## Boundaries and tensions
+
+Subtraction is a prompt, not proof of safety. It must not remove an implicit requirement,
+compatibility guarantee, security control, observability, or recovery path. First obey
+[P008 Understand Before Subtracting](p008-understand-before-subtracting.md) and
+[P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md). A necessary new control
+can increase code and decrease system risk.
+
+## Examples
+
+**Positive:** A product requirement specifies a mode. A contributor keeps the mode but deletes its
+duplicate configuration state. The command derives the mode from the repository's configuration authority.
+
+**Misuse:** A contributor removes a security check because tests give correct results. The contributor
+does not examine the trust boundary that the check gives protection to.
+
+**Athena/agent workflow:** Before an agent adds a documentation generator, the agent examines the
+runtime package for the canonical docs tree. The agent also does a test of standard links for discovery.
+
+## Related principles
+
+- [P001 KISS](p001-kiss.md)
+- [P008 Understand Before Subtracting](p008-understand-before-subtracting.md)
+- [P074 Prefer Existing Mechanisms](p074-prefer-existing-mechanisms.md)
+- [P088 Delete Dead Code](p088-delete-dead-code.md)
+- [P089 Delete Obsolete Configuration and Dependencies](p089-delete-obsolete-configuration-and-dependencies.md)
+- [P090 Prefer Negative Code](p090-prefer-negative-code.md)
+
+## References
+
+### Source information
+
+- [Adams et al.: People systematically overlook subtractive changes](https://www.nature.com/articles/s41586-021-03380-y)
+  gives results from controlled studies about the human preference for additive solutions.
+- [PEP 20 — The Zen of Python](https://peps.python.org/pep-0020/) records a related rule that shows
+  simple designs are better than complex designs.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  tells reviewers to examine code complexity that is not necessary.
+
+### More information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows why small self-contained changes are easier to examine. It also shows why
+  change reversal becomes safer.
+
+[Back to the engineering principles catalog](../README.md#p007)

package/skills/_support/docs/principles/details/p008-understand-before-subtracting.md

@@ -0,0 +1,115 @@
+# P008 — Understand Before Subtracting
+
+## Definition
+
+For **Understand Before Subtracting**, evidence about the purpose of a mechanism is necessary before
+its removal. History, callers, tests, contracts, deployment behavior, and architecture can show
+requirements that the deletion site does not show.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No single historical source gives this rule. The rule includes software archaeology,
+information hiding, compatibility practice, and Chesterton's fence. Chesterton's fence makes
+it necessary to know the purpose of a boundary before removal.
+
+## Decision rule
+
+Before deletion or consolidation, find the mechanism's consumers, observable behavior, owner, and
+initial or current purpose. Then make sure that removal keeps each necessary contract.
+
+## How to apply
+
+- Find all consumers. Also find consumers with connections from other components.
+- Read the claims in tests and documentation. Make sure they agree with implementation and history.
+- Examine version history and issue context for compatibility or failure lessons.
+- Find security, migration, cleanup, and operation roles that calls with correct results do not always show.
+- When coverage is not sufficient, add more behavioral evidence before deletion.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Select a removal candidate"] --> B["Find consumers, contracts, and history"]
+    B --> C["Find the mechanism's current purpose"]
+    C --> D{"Does evidence show safe removal?"}
+    D -->|No| E["Keep the mechanism"]
+    D -->|Yes| F["Remove the mechanism"]
+    F --> G["Make sure behavior is correct"]
+```
+
+## Language examples
+
+The two examples reject removal for an active consumer and make removal of a missing handler have no effect.
+
+```python
+def remove_handler(name: str, routes: list[Route], handlers: dict[str, Handler]) -> None:
+    if any(route.handler == name for route in routes):
+        raise ValueError("handler has a route")
+    handlers.pop(name, None)
+```
+
+```rust
+fn remove_handler(
+    name: &str, routes: &[Route], handlers: &mut HashMap<String, Handler>,
+) -> Result<(), &'static str> {
+    if routes.iter().any(|route| route.handler == name) {
+        return Err("handler has a route");
+    }
+    handlers.remove(name);
+    Ok(())
+}
+```
+
+## Boundaries and tensions
+
+The investigation must be sufficient for the risk. If evidence shows no consumers for an isolated
+local mechanism, do not examine all history. History is evidence, not an instruction to
+keep obsolete design. After analysis of purpose and consumers,
+[P007 Subtraction Over Addition](p007-subtraction-over-addition.md) and
+[P088 Delete Dead Code](p088-delete-dead-code.md) give evidence for safe removal. Repository policy and task
+authority specify if deletion is in scope.
+
+## Examples
+
+**Positive:** Before deletion of a compatibility parser, a maintainer examines callers, release
+notes, fixtures, telemetry, and supported-version policy. The maintainer removes it after support
+for the previous format stops.
+
+**Misuse:** A contributor deletes a branch because the current unit test does not select it. The
+contributor has no evidence about execution paths to the branch. Production configuration can select it.
+
+**Athena/agent workflow:** An agent reads the package builder and archive tests before a new
+manifest proposal. The agent also examines all consumers before documentation deletion.
+
+## Related principles
+
+- [P007 Subtraction Over Addition](p007-subtraction-over-addition.md)
+- [P012 Evidence Before Modification](p012-evidence-before-modification.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P018 Information Hiding](p018-information-hiding.md)
+- [P066 Preserve Existing Work](p066-preserve-existing-work.md)
+- [P088 Delete Dead Code](p088-delete-dead-code.md)
+
+## References
+
+### Source information
+
+- [David Parnas: On the Criteria To Be Used in Decomposing Systems into Modules](https://doi.org/10.1145/361598.361623)
+  shows why local selections can hide decisions that are important to consumers. Athena gives Parnas
+  no source attribution for this rule.
+
+### Applicable information
+
+- [Google Engineering Practices: Navigating a CL in review](https://google.github.io/eng-practices/review/reviewer/navigate.html)
+  recommends analysis of a change in its related files and system.
+- [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) gives information about why
+  removal of public behavior can cause a change that is not compatible.
+
+### More information
+
+- [Git documentation: git-log](https://git-scm.com/docs/git-log) is the primary tool to examine
+  change history and applicable context.
+
+[Back to the engineering principles catalog](../README.md#p008)

package/skills/_support/docs/principles/details/p009-general-mechanisms-over-special-cases.md

@@ -0,0 +1,108 @@
+# P009 — General Mechanisms Over Special Cases
+
+## Definition
+
+For **General Mechanisms Over Special Cases**, use one rule, algorithm, data model, or error
+path for the conditions in scope. When one invariant includes the conditions, do not use collections of
+branches for each condition. A general mechanism encodes an invariant that evidence shows. It does not add
+extensibility with no evidence.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+The idea occurs in mathematics, language design, and software engineering. No source supplies
+sufficient evidence for the initial statement. PEP 20 gives a software statement of the idea. It shows that special cases
+must obey correct rules.
+
+## Decision rule
+
+When two or more conditions share one rule that evidence shows, encode that rule one time. When
+variation does not change the rule, show it in data or a contract. When a special case is for a
+different requirement, keep it.
+
+## How to apply
+
+- Before you select an abstraction, record the invariant that the conditions share.
+- Do not put necessary policy differences together with input differences that do not change policy.
+- Select a table, normalized representation, or stable protocol. Do not use branches in many locations.
+- Use the same rule to do a test of usual conditions, boundary conditions, unusual conditions, and errors.
+- If a different contract is not clear in one mechanism, keep clear exceptions.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Collect the conditions in scope"] --> B["Record the shared invariant"]
+    B --> C{"Do all conditions share one contract?"}
+    C -->|Yes| D["Encode one general mechanism"]
+    C -->|No| E["Keep explicit special cases"]
+    D --> F["Do a test of usual, boundary, unusual, and error conditions"]
+    E --> F
+```
+
+## Language examples
+
+The two examples show mode variation in data with one lookup rule.
+
+```python
+RATES = {"standard": 5, "express": 20}
+
+def shipping_cost(mode: str) -> int | None:
+    cost = RATES.get(mode)
+    return cost
+```
+
+```rust
+const RATES: [(&str, u32); 2] = [("standard", 5), ("express", 20)];
+
+fn shipping_cost(mode: &str) -> Option<u32> {
+    RATES.iter().find(|(name, _)| *name == mode).map(|(_, cost)| *cost)
+}
+```
+
+## Boundaries and tensions
+
+Generalization has a maintenance cost. Two examples can have almost the same behavior without a
+shared invariant. [P013 AHA](p013-avoid-hasty-abstractions.md) and
+[P002 YAGNI](p002-yagni.md) give constraints for this principle. A clear explicit branch can have less
+complexity than a general engine with hidden policy. General mechanisms must keep specified
+failure causes and diagnostics that give value.
+
+## Examples
+
+**Positive:** Command variants share one parser and validation pipeline. Data shows
+their correct alternatives.
+
+**Misuse:** A configurable state-machine framework puts unrelated deployment workflows together because
+the two workflows have three steps.
+
+**Athena/agent workflow:** Review skills use one shared finding contract and add criteria for each
+surface. They do not make unrelated verdict formats for each review type.
+
+## Related principles
+
+- [P002 YAGNI](p002-yagni.md)
+- [P003 DRY](p003-dry.md)
+- [P013 AHA](p013-avoid-hasty-abstractions.md)
+- [P029 Generalize Error Policy; Preserve Specific Cause](p029-generalize-error-policy-preserve-specific-cause.md)
+- [P075 Make Invalid States Hard to Represent](p075-make-invalid-states-hard-to-represent.md)
+
+## References
+
+### Source information
+
+- [PEP 20 — The Zen of Python](https://peps.python.org/pep-0020/) is a primary language-design
+  statement about general rules, practicality, readability, and explicitness.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  tells reviewers to examine design, functionality, complexity, and architecture that is not necessary.
+
+### More information
+
+- [Sandi Metz: The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction)
+  shows that correction of an incorrect generalization can cost more than duplication.
+
+[Back to the engineering principles catalog](../README.md#p009)

package/skills/_support/docs/principles/details/p010-scope-fidelity.md

@@ -0,0 +1,117 @@
+# P010 — Scope Fidelity
+
+## Definition
+
+**Scope Fidelity** keeps a change in the scope of the specified requirement and necessary work. Cleanup that changes
+more code than necessary is not part of the change without authority for that work. This rule also
+includes cleanup in a component that contains the necessary change. Adjacent features, dependency
+upgrades, redesign, and improvements with no requirement are also out of scope without authority.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Athena gives this name to a rule from established change management, iterative development, and review
+practices. Athena gives no single historical source for the rule.
+
+## Decision rule
+
+Each artifact change must have a clear link to a requirement, acceptance criterion,
+defect, invariant, or necessary implementation dependency. If a change has no trace, keep it out of
+scope. With approved scope expansion, add the change to the scope.
+
+## How to apply
+
+- Before an edit, write the requested outcome, constraints, and acceptance criteria.
+- Keep necessary work isolated from cleanup that has no requirement.
+- Keep a clear link from each artifact change to the task requirement.
+- Give information about adjacent problems. Do not change them without authority.
+- When possible, put work with a different purpose in a different issue or change.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Write the accepted requirement"] --> B["Write each proposed change"]
+    B --> C{"Does the change have a link to the requirement?"}
+    C -->|No| D{"Does approved scope include the change?"}
+    D -->|No| G["Keep the change out of scope"]
+    D -->|Yes| E["Include necessary evidence and migration work"]
+    C -->|Yes| E
+    E --> F["Make sure the scope is correct"]
+```
+
+## Language examples
+
+The two examples use timeout values from 1 to 18,446,744,073,709,551,615 and change only the requested field.
+
+```python
+U64_MAX = 2**64 - 1
+
+def with_timeout(config: dict, timeout: int) -> dict:
+    if type(timeout) is not int or not 1 <= timeout <= U64_MAX:
+        raise ValueError("timeout is not in the u64 range")
+    updated = config.copy()
+    updated["timeout"] = timeout
+    return updated
+```
+
+```rust
+fn with_timeout(mut config: Config, timeout: u64) -> Result<Config, &'static str> {
+    if timeout == 0 {
+        return Err("timeout is not in the u64 range");
+    }
+    config.timeout = timeout;
+    Ok(config)
+}
+```
+
+## Boundaries and tensions
+
+All necessary parts must be in a scope-faithful patch. Necessary tests, documentation, migration,
+security controls, and compatibility work are necessary for a solution that obeys all requirements. An unrelated refactor
+is not necessary only because a person tells authors to do the refactor first. Repository safety and
+quality rules are mandatory when the prompt does not include them. Use
+[P011 Minimal Coherent Change](p011-minimal-coherent-change.md) to find the necessary boundary.
+
+## Examples
+
+**Positive:** A parser defect correction changes the parser, adds a regression test, and changes its
+public behavior note. It does not reformat adjacent modules.
+
+**Misuse:** A contributor corrects one flag, renames all commands in the family, and upgrades
+unrelated dependencies.
+
+**Athena/agent workflow:** An agent records unrelated findings for future work. The current diff
+contains only work for the user request and repository evidence requirements.
+
+## Related principles
+
+- [P002 YAGNI](p002-yagni.md)
+- [P011 Minimal Coherent Change](p011-minimal-coherent-change.md)
+- [P012 Evidence Before Modification](p012-evidence-before-modification.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P063 Requirement-to-Code Traceability](p063-requirement-to-code-traceability.md)
+- [P066 Preserve Existing Work](p066-preserve-existing-work.md)
+
+## References
+
+### Source information
+
+- [Manifesto for Agile Software Development: Principles](https://agilemanifesto.org/principles.html)
+  gives historical primary statements about initial, continuous, and simple delivery. It does not
+  include Athena's term “scope fidelity.”
+
+### Applicable information
+
+- [Athena development and delivery policy](../../policies/development.md) gives the repository's
+  mandatory scope, artifact, and validation rules.
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows why one self-contained change is for one issue.
+
+### More information
+
+- [Google Engineering Practices: The standard of code review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+  connects review decisions to code health without a requirement to correct unrelated defects.
+
+[Back to the engineering principles catalog](../README.md#p010)

package/skills/_support/docs/principles/details/p011-minimal-coherent-change.md

@@ -0,0 +1,128 @@
+# P011 — Minimal Coherent Change
+
+## Definition
+
+A **Minimal Coherent Change** is the smallest self-contained change for one specified purpose.
+It includes the necessary tests, documentation, migration, and safety work. Each part is
+necessary for that purpose. The change keeps unrelated work out.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Athena gives this name to a rule from established incremental delivery and code review guidance. Small
+changes are easier to examine. A change must also let a reviewer examine all parts and let the
+system operate safely.
+
+## Decision rule
+
+Select the narrowest boundary that keeps the specified behavior correct and that evidence shows is necessary.
+Put parts with different purposes in different changes. If separation causes an incorrect state
+after one step or prevents an applicable test, keep the parts together.
+
+## How to apply
+
+- Write the change's single purpose.
+- Include all necessary behavior, tests, contract updates, and migration handling.
+- Put cleanup, formatting, dependency updates, and refactors that the requirement does not include
+  in a different change.
+- Write commits that keep repository invariants and let a reviewer examine each commit.
+- After the change, examine the diff for files or hunks that are not necessary for the specified purpose.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Write one purpose"] --> B["Write necessary behavior and evidence"]
+    B --> C["Include all necessary parts"]
+    C --> D{"Is each part necessary for the purpose?"}
+    D -->|No| E["Move the unrelated part to a different change"]
+    E --> D
+    D -->|Yes| F["Make sure all parts of the change are correct"]
+```
+
+## Language examples
+
+The two examples remove the same ASCII whitespace, accept ASCII digits from 1 to 4,294,967,295,
+and give the `limit is not correct` error for all incorrect input.
+
+```python
+MAX_LIMIT = 4_294_967_295
+def parse_limit(text: str) -> int:
+    normalized = text.strip(" \t\r\n")
+    if not normalized.isascii() or not normalized.isdigit():
+        raise ValueError("limit is not correct")
+    try:
+        limit = int(normalized)
+    except ValueError as error:
+        raise ValueError("limit is not correct") from error
+    if not 1 <= limit <= MAX_LIMIT:
+        raise ValueError("limit is not correct")
+    return limit
+```
+
+```rust
+fn parse_limit(text: &str) -> Result<u32, &'static str> {
+    let normalized = text.trim_matches(|ch| matches!(ch, ' ' | '\t' | '\r' | '\n'));
+    if normalized.is_empty() || !normalized.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err("limit is not correct");
+    }
+    let limit = normalized.parse::<u32>().map_err(|_| "limit is not correct")?;
+    if limit == 0 {
+        return Err("limit is not correct");
+    }
+    Ok(limit)
+}
+```
+
+## Boundaries and tensions
+
+Minimal does not mean the minimum number of lines or a patch without all necessary parts. A one-line
+schema change without its migration and checks can be smaller but does not contain all necessary parts. Cleanup does
+not become necessary only because it changes the same file.
+[P010 Scope Fidelity](p010-scope-fidelity.md) gives the necessary purpose boundary.
+[P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md) and
+[P021 Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md) give constraints for
+delivery of the change.
+
+## Examples
+
+**Positive:** A configuration rename includes compatible parsing, migration documentation, and
+tests in one change. Unrelated configuration cleanup is in a different change.
+
+**Misuse:** A defect correction has two parts. The design of the first commit makes the build
+incorrect. The second commit makes it correct again. A reviewer cannot examine each commit independently.
+
+**Athena/agent workflow:** An agent edits only the canonical skills and shared docs for one issue.
+The agent does repository validation and keeps unrelated files out of the diff.
+
+## Related principles
+
+- [P001 KISS](p001-kiss.md)
+- [P010 Scope Fidelity](p010-scope-fidelity.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P021 Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md)
+- [P063 Requirement-to-Code Traceability](p063-requirement-to-code-traceability.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+
+## References
+
+### Source information
+
+- [Manifesto for Agile Software Development: Principles](https://agilemanifesto.org/principles.html)
+  is a primary historical source for incremental delivery and simplicity. It does not give
+  Athena's specified term.
+
+### Applicable information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows why a small, self-contained change is for one issue and includes its tests.
+- [Athena development and delivery policy](../../policies/development.md) gives the repository's
+  mandatory rules for change scope and artifacts.
+
+### More information
+
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) gives a
+  convention for communication of commit purpose and compatibility effects.
+
+[Back to the engineering principles catalog](../README.md#p011)