@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/_support/docs/principles/details/p065-verify-before-claiming-completion.md

@@ -0,0 +1,129 @@
+# P065 — Verify Before Claiming Completion
+
+## Definition
+
+Before a completion claim, examine the last change. Run the applicable checks that the repository
+specifies. Report the command, revision, environment, result, and important verification gaps.
+
+**Aliases:** evidence-backed completion, validation before a success claim.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+This rule uses established verification practice and evidence from software delivery. No verified
+source owns this rule. Athena's evidence-integrity policy specifies accurate reports with recorded
+commands, revisions, and environments.
+
+## Decision rule
+
+Do not report an expectation as a completion claim. Examine the delivered state. Use current,
+risk-based evidence. Limit the claim to facts that the evidence proves.
+
+## How to apply
+
+- Review the last diff and all generated, staged, and untracked artifacts in scope.
+- Run the necessary tests, build checks, type checks, lint checks, static checks, security checks,
+  and package checks.
+- Use the last revision and applicable environment. Do not use stale results.
+- Record commands, exit status, revision, environment, and important limitations.
+- Report failures, skips, unavailable dependencies, and timeouts. Do not report a pass result
+  without evidence.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Examine last change"] --> B["Select necessary checks for risk"]
+    B --> C["Run checks on last revision"]
+    C --> D{"Necessary evidence passes?"}
+    D -- "No" --> E["Report failure or evidence gap"]
+    D -- "Yes" --> F["Record command, revision, and environment"]
+    F --> G["Make evidence-bound completion claim"]
+```
+
+## Language examples
+
+The two examples show completion only if the expected-check set is not empty and each check has a
+current pass result.
+
+```python
+def completion_report(revision, expected, results):
+    current = {
+        name: check for name, check in results.items()
+        if check.revision == revision
+    }
+    missing = sorted(expected.difference(current))
+    failed = sorted(name for name in expected if name in current and not current[name].passed)
+    complete = bool(expected) and not missing and not failed
+    return Report(revision, complete, missing, failed)
+```
+
+```rust
+fn completion_report(revision: &str, expected: &HashSet<String>,
+                     results: &HashMap<String, Check>) -> Report {
+    let current = |name: &String| {
+        results.get(name).filter(|check| check.revision.as_str() == revision)
+    };
+    let missing = expected.iter().filter(|name| current(*name).is_none()).cloned().collect();
+    let failed = expected.iter()
+        .filter(|name| current(*name).is_some_and(|check| !check.passed))
+        .cloned().collect();
+    let complete = !expected.is_empty() && missing.is_empty() && failed.is_empty();
+    Report::new(revision, complete, missing, failed)
+}
+```
+
+## Boundaries and tensions
+
+Use risk-based evidence. Documentation, configuration, and production changes use different
+evidence. Checks that pass cannot prove requirements that the checks do not
+exercise.
+
+Cost does not supply evidence for an unverified claim. If a necessary check cannot run, report the
+gap. Also report the command or environment that can give the missing evidence. Do not bypass the
+gate.
+[P068 No Validation Bypass](p068-no-validation-bypass.md) specifies this rule.
+
+## Examples
+
+**Positive:** An author examines the last diff and runs the necessary gate at the current commit.
+The report identifies one unavailable platform test and does not claim that all tests pass.
+
+**Misuse:** A developer changes code after a test passes. The developer cites that stale result
+as proof for the new revision.
+
+**Athena/agent workflow:** Before completion, an agent runs `just all` and reports the command
+result.
+If the full gate cannot complete, the agent identifies each narrower check.
+
+## Related principles
+
+- [P012 Evidence Before Modification](p012-evidence-before-modification.md)
+- [P047 Observability Is Part of Correctness](p047-observability-is-part-of-correctness.md)
+- [P064 Requirement-to-Test Traceability](p064-requirement-to-test-traceability.md)
+- [P068 No Validation Bypass](p068-no-validation-bypass.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [NIST IR 8397, Guidelines on Minimum Standards for Developer Verification of Software](https://doi.org/10.6028/NIST.IR.8397)
+  records a current consensus set of verification techniques. Athena does not identify it as the
+  initial source for this rule.
+
+### Applicable information
+
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) specifies review, analysis, and testing
+  practices for software verification before release.
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  states that reviewers must examine function, tests, design, and the full change context.
+
+### More information
+
+- [Athena evidence integrity policy](../../policies/evidence-integrity.md) specifies the
+  repository's contract for accurate completion-evidence reports with recorded commands, revisions,
+  and environments.
+
+[Back to the engineering principles catalog](../README.md#p065)

package/skills/_support/docs/principles/details/p066-preserve-existing-work.md

@@ -0,0 +1,114 @@
+# P066 — Preserve Existing Work
+
+## Definition
+
+Do not revert, overwrite, reformat, regenerate, delete, or remove work from a different task.
+Identify earlier modifications. Isolate task-owned edits from them. When you cannot keep the two
+sets of work together, stop the task. Before you continue, isolate the task.
+
+**Aliases:** worktree preservation, noninterference with earlier changes.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No verified source specifies this rule. The rule uses version-control safety,
+narrow-change practice, and collaborative ownership. The rule gives agents a clear contract for a
+shared workspace.
+
+## Decision rule
+
+Before an edit or removal, identify if the path contains work from a different task. If you cannot
+keep that work, do not discard or overwrite it without specified authority. Use safe isolation.
+If safe isolation is not possible, tell the user that direction is necessary.
+
+## How to apply
+
+- Before an edit or cleanup, examine working-tree, index, branch, and worktree state.
+- Attribute changes from the initial state, task scope, and current diff.
+- Edit only specified paths. Stage only specified pathsets.
+- When concurrent changes cannot be safe together, use an isolated branch or linked worktree.
+- Report conflicts or ownership that is not clear. Do not use deletion to resolve them.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Examine path and repository state"] --> B{"Is work from a different task in this path?"}
+    B -- "No" --> C["Edit specified task paths"]
+    B -- "Yes" --> D{"Are the two changes safe together?"}
+    D -- "Yes" --> C
+    D -- "No" --> E["Use isolated worktree or stop"]
+    C --> F["Review task-owned diff"]
+```
+
+## Language examples
+
+The two examples change the task-owned field and keep all other fields.
+
+```python
+def update_owned_field(record, value):
+    result = record.copy()
+    result["owned"] = value
+    return result
+```
+
+```rust
+fn update_owned_field(record: &Record, value: String) -> Record {
+    let mut result = record.clone();
+    result.owned = value;
+    result
+}
+```
+
+## Boundaries and tensions
+
+Preservation does not make earlier changes immutable. The user can specify a modification,
+replacement, or removal. A scoped task can make careful edits to a modified file necessary. A
+generated product artifact can also make coherent regeneration necessary.
+
+The rule does not authorize data loss without a report or churn that is not part of the task. It
+does not prevent authorized collaboration. Do not discard uncommitted work only to make the
+repository clean.
+
+## Examples
+
+**Positive:** An agent finds edits from a different task in the primary checkout. The agent uses a
+new linked worktree and stages only the feature paths.
+
+**Misuse:** A formatter rewrites the full repository to simplify review of one patch. A reset also
+removes modifications with ownership that is not known.
+
+**Athena/agent workflow:** A delegated writer finds a second agent on the same skill. The writer
+does not edit the overlapping skill file and reports the overlap to the coordinator.
+
+## Related principles
+
+- [P010 Scope Fidelity](p010-scope-fidelity.md)
+- [P011 Minimal Coherent Change](p011-minimal-coherent-change.md)
+- [P021 Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- [Git worktree documentation](https://git-scm.com/docs/git-worktree) gives information about linked
+  worktrees. Its example isolates a high-priority change from active work. It is not the initial
+  source for this full principle.
+
+### Applicable information
+
+- [Git status documentation](https://git-scm.com/docs/git-status) specifies inspection of staged,
+  unstaged, and untracked working-tree state before an action.
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  recommends a different change for a refactor. It also recommends a narrow conceptual focus for
+  each change.
+
+### More information
+
+- [Git restore documentation](https://git-scm.com/docs/git-restore) states that restoration
+  can replace working-tree content or remove paths. This result makes earlier target resolution
+  necessary.
+
+[Back to the engineering principles catalog](../README.md#p066)

package/skills/_support/docs/principles/details/p067-no-test-cheating.md

@@ -0,0 +1,126 @@
+# P067 — No Test Cheating
+
+## Definition
+
+When an implementation violates its intended contract, fix the implementation. Do not decrease
+evidence quality.
+
+Do not delete or skip a correct test. Do not change assertions to accept incorrect results. Do not
+add mocks with a large scope. Do not report a failure as expected without contract evidence. Do not
+change expected values only to make the test pass.
+
+**Aliases:** preserve test integrity, no false success.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+This phrase is an Athena rule with no verified initial source. The rule formalizes a property of
+tests that give applicable evidence. Such a test rejects defective behavior and agrees with the
+accepted contract.
+
+## Decision rule
+
+When a test fails, identify if the implementation, test, environment, or requirement is incorrect.
+Only when evidence proves an error in the test contract, setup, or assertion, change the test. An
+accepted requirement change can also make a test change necessary. A delivery schedule problem does
+not make the change necessary.
+
+## How to apply
+
+- Reproduce the failure. Make sure that the test observes the specified behavior.
+- Compare the expectation with current requirements and public contracts.
+- When the implementation is incorrect, fix product behavior. Keep the regression test.
+- Repair intermittent setup failures, invalid fixtures, or stale expectations with recorded
+  evidence.
+- Keep mocks narrow to exercise integration and failure behavior.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Reproduce test failure"] --> B["Compare test with accepted contract"]
+    B --> C{"Implementation violates contract?"}
+    C -- "Yes" --> D["Fix implementation and keep test"]
+    C -- "No" --> E{"Is the test or requirement incorrect?"}
+    E -- "Yes" --> F["Correct test with evidence"]
+    E -- "No" --> G["Examine environment"]
+    D --> H["Run applicable test again"]
+    F --> H
+    G --> H
+```
+
+## Language examples
+
+The two examples keep a specified denial contract for a guest request.
+
+```python
+def test_guest_cannot_delete():
+    request = DeleteRequest(role="guest")
+    response = delete_resource(request)
+    assert response.status == 403
+```
+
+```rust
+#[test]
+fn guest_cannot_delete() {
+    let request = DeleteRequest::new(Role::Guest);
+    let response = delete_resource(request);
+    assert_eq!(response.status, 403);
+}
+```
+
+## Boundaries and tensions
+
+Tests can contain defects and do not automatically specify the contract. An accepted contract change
+can make a test change necessary. Repair obsolete or nondeterministic tests. Do not keep them only
+to satisfy a process requirement.
+
+Repository policy can authorize a narrow, documented skip for an unsupported environment. The skip
+does not prove a pass result for the missing test. Use evidence from
+[P072](p072-technical-evidence-over-preference.md) for the contract decision.
+
+## Examples
+
+**Positive:** A regression test shows a missing authorization check. The author fixes the
+implementation and keeps the test. The test fails if the defect returns.
+
+**Misuse:** An author changes a failed assertion from a specified denied status to one that accepts
+all responses. No requirement makes the change necessary. The author does not correct the defect.
+
+**Athena/agent workflow:** An agent examines a validator contract failure. The agent corrects the
+validator or a fixture that evidence proves incorrect. The agent does not change prose or delete the
+case only to pass
+`just test`.
+
+## Related principles
+
+- [P022 Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P026 Regression Before Repair](p026-regression-before-repair.md)
+- [P064 Requirement-to-Test Traceability](p064-requirement-to-test-traceability.md)
+- [P068 No Validation Bypass](p068-no-validation-bypass.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [Google Engineering Practices: What to look for in tests](https://google.github.io/eng-practices/review/reviewer/looking-for.html#tests)
+  states that tests must be correct and give applicable evidence. Tests must also fail when code is
+  defective. Athena does not claim this source as the initial source for its label.
+
+### Applicable information
+
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) lists code review, analysis, and
+  executable tests as software verification controls before release.
+- [Google Engineering Practices: Tests in small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html#keep-related-test-code-in-the-same-cl)
+  states that logic changes must have applicable tests. It also states that refactors must have test
+  coverage.
+
+### More information
+
+- [pytest documentation: How to use skip and xfail](https://docs.pytest.org/en/stable/how-to/skipping.html)
+  documents permitted uses and results for skipped or expected-failure tests. These markers report a
+  limitation, not a test pass.
+
+[Back to the engineering principles catalog](../README.md#p067)

package/skills/_support/docs/principles/details/p068-no-validation-bypass.md

@@ -0,0 +1,119 @@
+# P068 — No Validation Bypass
+
+## Definition
+
+When a validator finds a problem, do not disable or bypass the validator. Do not report an incorrect
+validation result.
+
+Validators include type checks, lint rules, compiler warnings, security controls, CI gates,
+authorization checks, and runtime checks. Fix the cause. An exception must be narrow. Evidence must
+show its necessity. The repository's authorized process must include it.
+
+**Aliases:** no gate bypass, preserve validation integrity.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No verified source specifies this rule. The rule uses secure-development verification,
+defense in depth, and protected-branch practice. It gives contributors a clear constraint.
+
+## Decision rule
+
+When validation fails, use the result as evidence. Examine the cause. If evidence does not prove
+that the control is incorrect, do not decrease control coverage or enforcement. When the repository
+process authorizes a correction or exception, keep the intended protection.
+
+## How to apply
+
+- Reproduce the validation result. Identify the requirement that the control enforces.
+- Correct the implementation, configuration, dependency, or test that violates that requirement.
+- Use the standard ownership and review process to change a defective rule.
+- Keep a necessary suppression local. Record its cause. Make its review and removal easy.
+- If a check did not run or had a skip, report it. If no check ran, do not report a pass.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Validation reports a defect"] --> B["Identify protected requirement"]
+    B --> C{"Implementation violates requirement?"}
+    C -- "Yes" --> D["Correct implementation or configuration"]
+    C -- "No" --> E{"Does evidence prove the control incorrect?"}
+    E -- "Yes" --> F["Use authorized control-change process"]
+    E -- "No" --> G["Keep gate and report failure"]
+    D --> H["Run full validation again"]
+    F --> H
+```
+
+## Language examples
+
+The two examples stop publication when the validator reports an error.
+
+```python
+def publish(change):
+    errors = validate(change)
+    if errors:
+        raise ValidationError(errors)
+    repository.publish(change)
+```
+
+```rust
+fn publish(change: &Change) -> Result<(), Error> {
+    validate(change)?;
+    repository::publish(change)?;
+    Ok(())
+}
+```
+
+## Boundaries and tensions
+
+Validation mechanisms can give false positives or conflict with a new accepted requirement. They
+can also be unavailable. When the protection operates correctly and the change obeys repository
+policy, a correction is not a bypass. Before use, the repository must specify an emergency path.
+That path must keep necessary safeguards and record the exception. Administrative permission to
+bypass a gate does not give authority to use the bypass.
+
+## Examples
+
+**Positive:** A linter finds a dangerous shell command. The author corrects the command and keeps
+the rule active.
+
+**Misuse:** A pull request adds a suppression with a large scope or disables a necessary check. The
+author wants to complete the correction in less time.
+
+**Athena/agent workflow:** When `just all` fails, the agent examines and reports the result. The
+agent does not use `--no-verify` or edit expected output. It does not report a narrower command that
+passed as the full gate.
+
+## Related principles
+
+- [P020 Executable Architecture](p020-executable-architecture.md)
+- [P054 Defense in Depth](p054-defense-in-depth.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+- [P067 No Test Cheating](p067-no-test-cheating.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [NIST SP 800-218, Secure Software Development Framework 1.1](https://doi.org/10.6028/NIST.SP.800-218)
+  includes established secure review, analysis, and test practices. Athena does not claim it as the
+  initial source for this rule.
+
+### Applicable information
+
+- [GitHub: About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
+  documents enforceable review gates, status-check gates, and specified bypass controls.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) states that personnel must verify
+  human-readable and executable code. It also states that personnel must correct known
+  vulnerabilities before release.
+
+### More information
+
+- [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/)
+  gives a maintained basis for security verification requirements. It does not authorize gate
+  removal without approval.
+
+[Back to the engineering principles catalog](../README.md#p068)

package/skills/_support/docs/principles/details/p069-independent-review-for-high-risk-changes.md

@@ -0,0 +1,129 @@
+# P069 — Independent Review for High-Risk Changes
+
+## Definition
+
+An independent reviewer must examine each security-critical or availability-critical change. The
+review depth must match the risk. The reviewer must know the affected domain. The reviewer must
+examine the specified change and evidence. Agreement with the author's result is not sufficient.
+
+**Aliases:** independent technical review, qualified second review.
+
+## Provenance
+
+**Classification:** established principle.
+
+Michael Fagan documented independent software inspection at IBM during the 1970s. Code-review and
+secure-development guidance specify independent, domain-qualified assessment in proportion to risk.
+
+## Decision rule
+
+Before acceptance of a high-risk change, receive a review from a qualified reviewer who did not
+author the change. The reviewer must examine assumptions. The reviewer must examine evidence. The
+reviewer must report findings independently. Author agreement is not necessary.
+
+## How to apply
+
+- Classify risk from the changed trust boundaries, data, concurrency, migration, or operations.
+- Select reviewers for specialized areas such as security, privacy, cryptography, concurrency,
+  infrastructure, or the applicable domain.
+- Give the reviewer the requirements, specified revision, full diff, tests, and known limitations.
+- Record the author and reviewer conclusions independently.
+- Clearly record the resolution of material findings.
+- When impact and uncertainty increase, increase review independence and depth.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Classify change risk"] --> B{"High-risk change?"}
+    B -- "No" --> C["Use standard review path"]
+    B -- "Yes" --> D["Select qualified non-author reviewer"]
+    D --> E["Examine specified change and evidence"]
+    E --> F{"Material finding?"}
+    F -- "Yes" --> G["Resolve finding and revise change"]
+    G --> I["Examine specified revised change and evidence"]
+    I --> F
+    F -- "No" --> H["Record independent result"]
+```
+
+## Language examples
+
+The two examples use one immutable digest of the same change, author independence, and domain
+qualification before acceptance.
+
+```python
+def accept(change, review):
+    if review.change_digest != change.digest:
+        raise ValueError("review does not match change")
+    if review.author == change.author:
+        raise ValueError("reviewer is not independent")
+    if change.domain not in review.qualifications:
+        raise ValueError("reviewer is not qualified")
+    return review.approved
+```
+
+```rust
+fn accept(change: &Change, review: &Review) -> Result<bool, Error> {
+    if review.change_digest != change.digest {
+        return Err(Error::StaleReview);
+    }
+    if review.author == change.author {
+        return Err(Error::SameAuthor);
+    }
+    if !review.qualifications.contains(&change.domain) {
+        return Err(Error::UnqualifiedReviewer);
+    }
+    Ok(review.approved)
+}
+```
+
+## Boundaries and tensions
+
+A human reviewer is not always necessary for independent review. A qualified agent or specialist
+can do a new, bounded review. Repository policy can specify a human, Code Owner, regulated role, or
+approval count.
+Automated analysis can add evidence to a review but usually does not supply all contextual
+judgment. A non-author agreement without analysis is not an independent review. Low-risk work does
+not make a large review process necessary.
+
+## Examples
+
+**Positive:** A security specialist did not author an authorization change. The specialist reviews
+the specified commit, threat boundary, negative tests, and release behavior before acceptance.
+
+**Misuse:** A team member approves cryptographic code without an inspection or knowledge of the
+primitive. The approval only satisfies a necessary count.
+
+**Athena/agent workflow:** A coordinator assigns a high-risk diff to an independent review agent.
+The task has specified criteria. The criteria do not tell the reviewer to agree with the author's
+result.
+The coordinator reports unresolved findings to the user.
+
+## Related principles
+
+- [P052 Separation of Duties](p052-separation-of-duties.md)
+- [P054 Defense in Depth](p054-defense-in-depth.md)
+- [P061 Separate Decision from High-Impact Execution](p061-separate-decision-from-high-impact-execution.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+
+## References
+
+### Source information
+
+- [Fagan, "Design and Code Inspections to Reduce Errors in Program Development" (1976)](https://doi.org/10.1147/sj.153.0182)
+  is a primary account of structured software inspection with specified roles.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  states that authors must involve qualified reviewers for complex areas. Examples include security,
+  privacy, and concurrency.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) lists code review and analysis as
+  practices that identify vulnerabilities before release.
+
+### More information
+
+- [OWASP Secure Code Review Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Code_Review_Cheat_Sheet.html)
+  gives information about risk-based manual review and context that automated tools can miss.
+
+[Back to the engineering principles catalog](../README.md#p069)