@homericintelligence/athena-opencode 0.5.0 → 0.5.1

package/skills/_support/docs/principles/details/p090-prefer-negative-code.md

@@ -0,0 +1,134 @@
+# P090 — Prefer Negative Code
+
+## Definition
+
+**Prefer Negative Code** selects the smaller of two implementations that have the same correct
+behavior. Compare code, mutable state, configuration, dependencies, and concepts. The principle selects
+a possible fault surface that is smaller, not a smaller character count.
+
+**Aliases:** negative code and subtractive implementation.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Andy Hertzfeld's account about Bill Atkinson records the term. The account includes Atkinson's
+"-2000" line entry after a QuickDraw change. The story gives examples of errors in a productivity measure.
+The story does not give proof that line deletion makes software better. Athena uses the label for
+simplification with evidence.
+
+## Decision rule
+
+First, make sure that behavior and necessary quality are equal. Then, select the design with a
+smaller surface for maintenance and operation. Count concepts and duties, not raw lines.
+
+## How to apply
+
+- Remove obsolete branches, intermediaries, state, and configuration.
+- Derive data from one source. Do not keep copies that authors can change independently.
+- Replace custom machinery with an applicable repository mechanism.
+- Replace stable duplicate behavior with one implementation. Before behavior becomes stable, do not make an abstraction.
+- Compare readability, performance, security, operability, and compatibility before and after.
+- Do behavioral tests and examine the completed diff.
+
+## Diagram
+
+After tests give equal results, compare maintenance surfaces.
+
+```mermaid
+flowchart LR
+    A["Two correct designs"] --> B["Behavior-equivalence tests"]
+    B --> C["Compare state, code, and duties"]
+    C --> D{"One surface is smaller?"}
+    D -->|Yes| E["Select smaller surface"]
+    D -->|No| F["Select clear design"]
+```
+
+## Language examples
+
+The two examples use one status table, use the same domain for `u16` text, and reject malformed or
+out-of-range input.
+
+### Python
+
+```python
+STATUS_TEXT = ((200, "ok"), (404, "missing"), (503, "unavailable"))
+
+def status_text(text: str) -> str:
+    if not text.isascii() or not text.isdecimal():
+        raise ValueError("invalid status")
+    code = int(text)
+    if code > 65_535:
+        raise ValueError("invalid status")
+    return next((label for value, label in STATUS_TEXT if value == code), "unknown")
+```
+
+### Rust
+
+```rust
+const STATUS_TEXT: &[(u16, &str)] = &[(200, "ok"), (404, "missing"), (503, "unavailable")];
+
+fn status_text(text: &str) -> Result<&'static str, &'static str> {
+    if text.is_empty() || !text.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err("invalid status");
+    }
+    let code = text.parse::<u16>().map_err(|_| "invalid status")?;
+    Ok(STATUS_TEXT.iter()
+        .find_map(|(value, label)| (*value == code).then_some(*label))
+        .unwrap_or("unknown"))
+}
+```
+
+## Boundaries and tensions
+
+Code golf, compressed expressions, and hidden conventions can decrease line count and increase
+risk. Line counts are incorrect measures for generated code and declarative configuration. An
+abstraction can remove code and add a concept with more complexity. Duplication can be safer than an incorrect
+abstraction.
+Keep necessary validation, diagnostics, compatibility, and explicit contracts.
+
+## Examples
+
+**Positive:** A data-driven transition table replaces duplicate special-case branches. The table keeps
+states with names, validation, and error behavior.
+
+**Misuse:** A developer includes some clear checks in one expression. The expression is short but
+causes more inspection and diagnosis work.
+
+**Athena/agent workflow:** After verification that the package finds the canonical documentation tree,
+an agent removes a document registry with duplicate information. The agent keeps only the check that
+has a product consumer.
+
+## Related principles
+
+- [P001 KISS](p001-kiss.md)
+- [P007 Subtraction Over Addition](p007-subtraction-over-addition.md)
+- [P013 AHA](p013-avoid-hasty-abstractions.md)
+- [P074 Prefer Existing Mechanisms](p074-prefer-existing-mechanisms.md)
+- [P086 Readability Counts](p086-readability-counts.md)
+- [P088 Delete Dead Code](p088-delete-dead-code.md)
+
+## References
+
+### Source information
+
+- [Folklore.org: -2000 Lines Of Code](https://www.folklore.org/Negative_2000_Lines_Of_Code.html)
+  is Andy Hertzfeld's historical account of the Bill Atkinson story. The account is a historical
+  anecdote, not controlled evidence for a code-quality metric.
+
+### Applicable information
+
+- [Google SRE: Operational Simplicity](https://sre.google/sre-book/simplicity/) gives the difference
+  between necessary and accidental complexity. The guidance tells engineers to remove code with no
+  business function.
+- [Google SRE: Regaining Simplicity](https://sre.google/workbook/simplicity/) includes simplification
+  as engineering work that decreases cognitive and operation load.
+
+### More information
+
+- [People systematically overlook subtractive changes](https://www.nature.com/articles/s41586-021-03380-y)
+  gives experimental evidence for a general human bias for additive solutions. The study gives
+  subtraction as a possible solution. The study does not give proof that line count is a software-quality
+  measure.
+
+[Back to the engineering principles catalog](../README.md#p090)

package/skills/_support/docs/principles/details/p091-test-driven-development.md

@@ -0,0 +1,149 @@
+# P091 — Test-Driven Development
+
+## Definition
+
+**Test-Driven Development** (TDD) is a short development cycle. First, an automated test shows the
+next necessary behavior and fails. Then, the author makes the minimum necessary change to
+production code. The test then passes.
+After all tests pass, the author refactors production code while tests continue to pass. The cycle is Red-Green-Refactor.
+
+**Aliases:** TDD and Red-Green-Refactor cycle.
+
+## Provenance
+
+**Classification:** principle with source evidence.
+
+Before 2000, Kent Beck's Extreme Programming practice included the TDD practice. His 2002
+book, *Test-Driven Development: By Example*, records the practice. Athena keeps TDD because the TDD
+order gives fast behavior and design feedback.
+
+## Decision rule
+
+For one behavior change, use one Red-Green-Refactor cycle. Make sure the test gives the expected
+failure. Make the test pass with a correct production change. Then, refactor production code without
+a behavior change.
+
+## How to apply
+
+- Record the next necessary behaviors, important failures, and boundaries.
+- At a boundary where a user can see the result, write a test for one small behavior.
+- Do the test and make sure that the failure shows the missing behavior.
+- Write only the correct production code that is necessary to make all applicable tests pass.
+- While the suite passes, refactor tests and production code.
+- Do the cycle again. Then, do all necessary repository verification.
+
+## Diagram
+
+The cycle adds one behavior and keeps the design clear.
+
+```mermaid
+flowchart LR
+    A["Write one behavior test"] --> B["Do test and examine failure"]
+    B --> C["Make minimum correct change"]
+    C --> D{"Tests pass?"}
+    D -->|No| C
+    D -->|Yes| E["Refactor code"]
+    E --> G{"Post-refactor tests pass?"}
+    G -->|No| H["Correct refactor"]
+    H --> G
+    G -->|Yes| I{"More behavior?"}
+    I -->|Yes| F["Select next behavior"]
+    F --> A
+    I -->|No| J["Development completed"]
+```
+
+## Language examples
+
+The two examples give the behavior first, use the same domain for signed `i32` text, and reject
+malformed or out-of-range input.
+
+### Python
+
+```python
+def test_clamps_negative_count() -> None:
+    assert clamp_count("-1") == 0
+
+def clamp_count(text: str) -> int:
+    digits = text[1:] if text.startswith("-") else text
+    if not digits or not digits.isascii() or not digits.isdecimal():
+        raise ValueError("count must be i32")
+    value = int(text)
+    if not -(2**31) <= value <= 2**31 - 1:
+        raise ValueError("count must be i32")
+    return max(0, value)
+```
+
+### Rust
+
+```rust
+#[test]
+fn clamps_negative_count() {
+    assert_eq!(clamp_count("-1"), Ok(0));
+}
+
+fn clamp_count(text: &str) -> Result<i32, &'static str> {
+    let digits = text.strip_prefix('-').unwrap_or(text);
+    if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
+        return Err("count must be i32");
+    }
+    let value = text.parse::<i32>().map_err(|_| "count must be i32")?;
+    Ok(value.max(0))
+}
+```
+
+## Boundaries and tensions
+
+TDD is a development cycle, not the full test strategy. [P026 Regression Before
+Repair](p026-regression-before-repair.md) is applicable only to a defect. TDD is applicable to incremental
+behavior development. P022-P028 control test quality and scope.
+
+TDD controls work order. Verification also includes builds, types, lint, integration, security, and
+operation checks. A behavior-preserving refactor starts from a sufficient green baseline. Do not
+make a test fail only to record an incorrect Red step.
+
+## Examples
+
+**Positive:** A developer writes a behavioral test for the parser's next boundary case. The test
+fails because the parser does not have the behavior. A small implementation makes the test pass. The developer then removes
+duplication with a green suite.
+
+**Misuse:** A developer completes the implementation first. The developer then adds a test that
+has a dependency on private call order and records the work as TDD.
+
+**Athena/agent workflow:** For a behavior change, an agent records the expected test failure. The
+agent makes the minimum correct fix and does the applicable test suite again. Then, the agent
+refactors the code and does the repository verification gate. For a behavior-preserving refactor,
+the agent first records the green baseline.
+
+## Related principles
+
+- [P022 Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P026 Regression Before Repair](p026-regression-before-repair.md)
+- [P027 Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+- [P064 Requirement-to-Test Traceability](p064-requirement-to-test-traceability.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+- [P067 No Test Cheating](p067-no-test-cheating.md)
+
+## References
+
+### Source information
+
+- [Kent Beck, *Test-Driven Development: By Example*](https://ptgmedia.pearsoncmg.com/images/9780321146533/samplepages/0321146530.pdf)
+  is the publisher's sample of the book and gives the Red–Green–Refactor rules.
+- [Martin Fowler: Test Driven Development](https://martinfowler.com/bliki/TestDrivenDevelopment.html)
+  records the practice's Extreme Programming history and gives information about interface-design
+  feedback.
+
+### Applicable information
+
+- [The GDS Way: Test-driven development](https://gds-way.digital.cabinet-office.gov.uk/standards/test-driven-development.html)
+  gives government engineering guidance for expected-failure, green implementation, and
+  Red-Green-Refactor cycles. The guidance also gives examples where other feedback mechanisms are necessary.
+
+### More information
+
+- [Agile Alliance: Testing in agile software development](https://agilealliance.org/agile-qa-testing-in-agile-software-development/)
+  gives the differences between TDD, acceptance-test-driven practice, and behavior-driven practice.
+  The three practices help continuous quality.
+
+[Back to the engineering principles catalog](../README.md#p091)

package/skills/_support/docs/review/README.md

@@ -0,0 +1,59 @@
+# Review framework
+
+**Why:** Athena reviews must catch architecture and behavior regressions before lower-level checks
+create false confidence. The shared framework keeps that standard consistent while each skill uses
+the delivery channel appropriate to its scope. It applies the canonical
+[engineering principles](../principles/README.md) through review-specific profiles instead of
+redefining them.
+
+Use the [ASD-STE100 technical-English policy](../../../TECHNICAL_ENGLISH.md) for all technical prose and review
+output.
+
+## System at a glance
+
+```mermaid
+flowchart LR
+    Request["Review request"] --> Scope{"Scope"}
+    Scope --> Change["change-review"]
+    Scope --> Issue["plan-issue / issue-review / finalize-plan"]
+    Scope --> Pull["pr-review"]
+    Scope --> Repository["repo-review"]
+
+    Change --> Framework["Shared framework\narchitecture, then checks, then evidence"]
+    Issue --> Framework
+    Pull --> Framework
+    Repository --> Framework
+
+    Framework --> Findings["Deduplicated findings"]
+    Findings --> Delivery{"Authorized delivery"}
+    Delivery --> Console["Console or local annotations"]
+    Delivery --> IssueComment["Actor-owned issue comment"]
+    Delivery --> PullReview["One atomic PR review"]
+    Delivery --> Tracker["Tracker and child work items"]
+```
+
+## Components
+
+| Component | Owns | Read when |
+| --- | --- | --- |
+| [ASD-STE100 technical-English policy](../../../TECHNICAL_ENGLISH.md) | Method for technical prose and literal-text boundary. | Before you write or change technical prose or review output. |
+| [Shared contract](common.md) | Architecture gate, evidence, canonical-principle application profiles, findings, and delivery boundaries. | Every review. |
+| [Language routing](language-routing.md) | Applicable language and toolchain profile. | The changed or inventoried surface contains code or build tooling. |
+| [Behavior-first testing](behavior-first-testing.md) | Functional-test quality and false-confidence rules. | Tests, validation, or a plan are in scope. |
+| [Issue planning](issue-planning.md) | Canonical plan identity, review, and finalized-epoch artifacts. | Planning, reviewing, or finalizing an issue. |
+| [Repository scorecard](repository-scorecard.md) | Full-inventory repository criteria and scoring. | Reviewing a repository. |
+| [Design-document structure](design-docs.md) | A clear order for architecture and design decisions. | Writing a new mutable design document. |
+
+## Read order
+
+1. Read the ASD-STE100 technical-English policy.
+2. Read the shared contract and repository guidance.
+3. Confirm that the artifact aligns with the architecture.
+4. Classify the surface.
+5. Read only the applicable language and test guidance.
+6. If the scope includes issue planning, read the issue-planning contract.
+7. If the scope includes a repository review, read the repository scorecard.
+8. Follow the invoking skill for scope resolution and its authorized delivery channel.
+
+The diagram appears only here. Component documents use tables or prose when those communicate their
+own decision more clearly.

package/skills/_support/docs/review/behavior-first-testing.md

@@ -0,0 +1,73 @@
+# Behavior-first testing
+
+**Why:** Tests must prove core product behavior. They must fail if that behavior regresses. Do not
+make tests preserve wording, implementation layout, or incidental timing. This contract applies to
+planning, implementation, change review, pull request review, and repository review.
+
+Use the [ASD-STE100 technical-English policy](../../../TECHNICAL_ENGLISH.md) for all technical prose and review
+output.
+
+This contract applies the catalog's testing rules:
+[P022](../principles/README.md#p022), [P023](../principles/README.md#p023),
+[P024](../principles/README.md#p024), [P025](../principles/README.md#p025),
+[P026](../principles/README.md#p026), [P027](../principles/README.md#p027),
+[P028](../principles/README.md#p028), and [P091](../principles/README.md#p091).
+Apply only the rules that are relevant to the reviewed behavior and risk. Apply P091 to a behavior
+change that uses test-driven development (TDD). Apply the other rules independently when they are
+relevant.
+
+## What a good test proves
+
+A good test proves one observable product contract. The contract can specify:
+
+- a result;
+- a state transition;
+- a public error contract;
+- a security property;
+- a resource or performance limit; or
+- executable artifact behavior.
+
+Make each test deterministic and isolated. Make sure that its result does not depend on test order
+or ambient machine state. The test must fail if the regression occurs again.
+
+| Situation | Good test | Bad test |
+| --- | --- | --- |
+| API behavior | A request produces the documented result and rejects invalid or boundary input. | A private helper runs in a particular order. |
+| Bug fix | A regression crosses a public or architectural boundary and fails without the fix. | Only an issue number or TODO appears. |
+| State change | Durable state and externally visible transitions are correct on success and failure. | A snapshot freezes internal layout without an outcome assertion. |
+| Documentation | Markdown, links, and executable examples validate syntax, navigation, or real output. | A test pins wording, headings, paragraph counts, or documentation counts. |
+| Integration | Controlled substitutes exercise a real external boundary and error behavior. | A live service, wall-clock sleep, or ambient credential decides the result. |
+
+## Avoid flakiness and false confidence
+
+If the product contract does not require and control a condition, flag a test that depends on any of
+these conditions:
+
+- wall-clock delays;
+- unseeded randomness;
+- test order;
+- live network services;
+- current machine paths;
+- unspecified scheduling; or
+- shared mutable state.
+
+Use mocks only at genuine external boundaries. Do not count a test that only verifies its mock
+arrangement as behavior coverage. Use controlled time, seeded data, temporary paths, fake
+transports, and explicit synchronization.
+
+A name-filtered command can pass when it selects no tests. Before you accept `pytest -k`, `ctest -R`,
+`go test -run`, or an equivalent filter as evidence, verify that it selects at least one registered
+test. For CMake, also verify that a real build target includes the test source. Treat a successful
+command that runs no relevant test as a coverage failure.
+
+## Planning and review rules
+
+- Map each changed acceptance criterion to observable verification.
+- If no concrete documented constraint prevents a regression test, add one for every bug fix.
+- Verify error, boundary, and relevant concurrency paths proportionately to product risk.
+- Do not weaken, skip, xfail, delete, or mock around a test solely to make a change green.
+- Do not claim a benchmark, model metric, or runtime measurement succeeded without reproducible
+  execution evidence bound to the reviewed revision.
+
+Documentation-only changes use existing Markdown, link, and executable-example checks. They do not
+justify a prose-string test harness.