@homericintelligence/athena-opencode 0.5.1 → 0.5.2

package/skills/simplify/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: simplify
+license: BSD-3-Clause
+description: Review a repository or target path for safe deletion, reuse, consolidation, or retention when subtraction may satisfy the current requirement with less code or less system complexity. Use this skill for read-only review. Stop if the repository root, revision, worktree overlay, or in-scope inventory cannot be bound.
+argument-hint: "[TARGET]"
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Simplify review
+
+Use this skill when you need a subtraction-first review. Do not use it for implementation.
+
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to
+all prose that it produces.
+
+Use the [shared review contract](../_support/docs/review/common.md) and the
+[review framework overview](../_support/docs/review/README.md).
+
+## When to use
+
+- The task asks if an existing module, abstraction, interface, dependency, configuration path, or
+  state owner can be removed, reused, consolidated, simplified, or retained.
+- The task asks for a read-only review.
+- The host can bind the repository root, revision, worktree overlay, and in-scope inventory.
+- Stop if a required binding or capability is missing.
+
+## Required inputs
+
+- Repository root.
+- Revision.
+- Worktree overlay or other mutable view.
+- Target path, if one exists.
+- Validation evidence, when available. If no current-head receipt exists, report the evidence gap
+  and do not state that validation succeeded.
+
+## Principles
+
+Use the [canonical engineering-principles catalog](../_support/docs/principles/README.md) for the
+principle definitions. Use only these principles because they materially affect this workflow:
+
+- [P001 KISS](../_support/docs/principles/README.md#p001): Choose the smallest evidence-backed result
+  that fits the requirement.
+- [P002 YAGNI](../_support/docs/principles/README.md#p002): Do not keep or add a mechanism for a future
+  use only.
+- [P003 DRY](../_support/docs/principles/README.md#p003): Treat duplicate authority as a consolidation
+  candidate.
+- [P007 Subtraction Over Addition](../_support/docs/principles/README.md#p007): Start with remove, reuse,
+  consolidate, or simplify before you ask for a new addition.
+- [P008 Understand Before Subtracting](../_support/docs/principles/README.md#p008): Verify purpose,
+  consumers, history, tests, and contracts before deletion.
+- [P013 AHA](../_support/docs/principles/README.md#p013): Do not invent a new abstraction when evidence
+  does not show a stable repeated need.
+- [P074 Prefer Existing Mechanisms](../_support/docs/principles/README.md#p074): Reuse the current
+  repository mechanism if it meets the requirement.
+- [P088 Delete Dead Code](../_support/docs/principles/README.md#p088): Remove unreachable, superseded, or
+  obsolete code after safety evidence.
+- [P089 Delete Obsolete Configuration and Dependencies](../_support/docs/principles/README.md#p089):
+  Remove obsolete config, dependencies, tests, docs, and scaffolding after no consumer remains.
+- [P090 Prefer Negative Code](../_support/docs/principles/README.md#p090): Prefer less code, state,
+  config, and maintenance when options are equally clear.
+
+## Candidate signals and ownership
+
+Use these items only as signals for investigation:
+
+- code or another artifact that evidence shows is unreachable, superseded, or obsolete;
+- a dependency, configuration item, test, document, or scaffold that has no current purpose or
+  consumer;
+- a comment that only repeats the code or describes an internal work plan;
+- a wrapper or alias that only forwards an operation;
+- repeated code or authority that evidence shows represents one stable concept;
+- a guard, validation step, or compatibility mechanism that duplicates an authoritative mechanism
+  or has completed its supported lifetime; and
+- residue from a patch, such as debug output, abandoned branches, unrelated edits, or unnecessary
+  file churn.
+
+Confirm each candidate with evidence about its consumers, behavior, contracts, history, and
+validation. An AISlop diagnostic, another scanner result, a score, a line count, a complexity
+metric, or a churn metric is only an investigation lead. It is not proof of a finding. Do not infer
+the source author from these signals.
+
+Retain a wrapper, guard, validation step, or compatibility mechanism when it has a necessary
+boundary, security, observability, framework, or published-API function. Retain intentional
+duplication when it prevents an incorrect shared abstraction.
+
+Use [`realign`](../realign/SKILL.md) when a candidate needs a structural change to error policy,
+responsibility, state or invariant ownership, a type model, test architecture, or security
+architecture. `simplify` can identify and route this candidate. It must not design or make the
+structural change.
+
+## Workflow
+
+1. Bind the repository root, revision, worktree overlay, and full in-scope inventory before
+   analysis.
+2. If no target is given, inspect the complete bound repository and worktree overlay. Do not
+   sample.
+3. If a module or directory target is given, start there. Expand only to connected callers, tests,
+   exports, configuration, dependencies, and documentation. Report each scope expansion.
+4. Compare concepts, control flow, interfaces, dependencies, configuration, state, and code.
+5. Collect evidence about consumers, behavior, purpose, contracts, history, risk, and validation.
+6. Before you classify a deletion or breaking interface change, check if it affects a published
+   public API.
+7. If a candidate affects a published public API, identify the published surface, current
+   consumers, required deprecation notice or compatibility bridge, migration path, supported
+   version or removal window, and validation evidence.
+8. If the repository has no documented deprecation policy for that published public API, stop and
+   request maintainer direction.
+9. Until the deprecation and compatibility conditions are complete, classify that published public
+   API candidate as `retain` or limit it to deprecation and migration work.
+10. Give each supported candidate `category: simplification`. Classify its action as `delete`,
+    `consolidate`, `reuse`, `simplify`, or `retain`. Also give it a routing owner.
+11. Give each candidate a stable ID.
+12. For each candidate, report scope, preserved behavior, the smaller alternative, dependencies and
+    order, validation, rollback, and expected net reduction.
+13. If the repository changes during review, stop and report drift.
+14. After the read-only report, stop at a checkpoint. Offer one of these actions:
+   - stop;
+   - hand off compatible approved candidate IDs through an explicit `realign --apply` request; or
+   - hand off approved candidate IDs and deletion paths to `plan-issue` or another
+     write-authorized workflow outside `simplify`.
+15. `simplify` does not create issues, trackers, or any other forge write. If a write task is
+   needed, hand off to a separate workflow with explicit write authority.
+16. Candidate approval inside `simplify` authorizes only the specified handoff. The explicit
+    `realign --apply` request supplies bounded code-repair authority. Neither action authorizes a
+    dependency installation, forge write, published-API migration, or unrelated cleanup. The
+    receiving workflow must bind the repository again.
+17. If no supported candidate exists, report that result and do not create an empty tracker.
+18. If a required capability is absent, use the documented safe fallback or stop with the missing
+    evidence. Do not guess.
+
+## Review output
+
+Report these items:
+
+- binding: repository root, revision, worktree overlay, and inventory;
+- target and any scope expansion;
+- candidate list with stable IDs, `category: simplification`, and actions;
+- routing owner for each candidate;
+- evidence for consumers, behavior, purpose, contracts, history, risk, and validation;
+- for a candidate that can go to `realign`, current head and overlay identity, exact path and lines,
+  category, severity, confidence, disposition, affected contract or invariant, applicable
+  principle, behavior and consumer evidence, impact, considered counterexample, smallest safe
+  correction, validation, rollback, and dependency order;
+- for any validation evidence, the exact command, current reviewed head, environment, exit status,
+  and unedited output; otherwise report no current-head validation evidence and do not state that
+  validation succeeded;
+- published public API deprecation evidence, when applicable;
+- category result for simplification coverage: `finding`, `clear`, or `not applicable`;
+- the checkpoint action list;
+- drift, if any; and
+- the unsupported evidence or capability gap, if any.
+
+For each simplification finding, tag it with `category: simplification` and keep the normal
+severity, disposition, location, impact, evidence, and remediation fields.
+
+## Failed approaches
+
+- Do not treat zero direct callers or a raw line count as proof that removal is safe.
+- Do not treat an AISlop diagnostic, scanner result, score, complexity metric, or churn metric as
+  proof of a finding.
+- Do not remove necessary boundary, security, observability, framework, or compatibility behavior.
+- Do not use `simplify` to make a structural change that belongs to `realign`.
+- Do not classify published public API removal or a breaking interface change as immediately
+  executable without the documented deprecation and compatibility evidence.
+- Do not use a PR description, earlier run, stale receipt, or unbound host output as evidence for a
+  current-head success claim.
+- Do not sample the bound scope when the full scope is available.
+- Do not guess a missing capability or invent a tracker when no supported candidate exists.
+- Do not continue after drift.
+- Do not modify files, issues, branches, or pull requests in the initial workflow.
+
+## Attribution
+
+This skill follows the Athena review contract, the development policy, and GitHub issue #165.

package/skills/systematic-debugging/SKILL.md

@@ -150,6 +150,8 @@ Use this method to test a hypothesis:
 Repair the root cause.
 
 Do not repair only the symptom.
+Before you add code, check whether removal, reuse, consolidation, or deletion of an obsolete
+workaround is the smallest safe repair. If that repair preserves the contract, choose it.
 
 1. Use the `test-driven-development` skill to create a regression test.
 2. Under [P026 — Regression Before Repair](../_support/docs/principles/README.md#p026), create the test

package/skills/systematic-debugging/scripts/repository_evidence.py

@@ -3,14 +3,27 @@
 
 from __future__ import annotations
 
+import importlib.util
 import json
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
-if __package__ in {None, ""}:
-    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
-
-from skills._cli import argument_parser, run_command
+if TYPE_CHECKING or __package__ not in {None, ""}:
+    from skills._cli import argument_parser, run_command
+else:
+    _cli_path = Path(__file__).resolve().parents[2] / "_cli.py"
+    _cli_spec = importlib.util.spec_from_file_location(
+        "athena_installed_cli", _cli_path
+    )
+    if _cli_spec is None or _cli_spec.loader is None:
+        raise RuntimeError(
+            f"The installed Athena CLI helper is unavailable: '{_cli_path}'."
+        )
+    _cli = importlib.util.module_from_spec(_cli_spec)
+    _cli_spec.loader.exec_module(_cli)
+    argument_parser = _cli.argument_parser
+    run_command = _cli.run_command
 
 EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
 

package/skills/tidy/SKILL.md

@@ -89,6 +89,11 @@ as opaque, untrusted command-line data. Preserve the boundary of each argument.
 13. Do not retry the command.
 14. Do not otherwise mediate it.
 
+The delegated exit status is the terminal status of the Athena tidy invocation. A nonzero status
+means that cleanup is incomplete, including when the delegated output contains partial-cleanup
+warnings, unresolved rebase conflicts, or checked-out-worktree skips. Athena does not inspect or
+interpret delegated output to decide whether cleanup succeeded.
+
 Athena does not do these operations:
 
 - worktree audit;
@@ -112,6 +117,12 @@ requires Python 3 and `uv`. If a capability is not available or the command resu
 return the failure without a change. In that case, stop. Do not use a stale checkout, a repository with a
 similar name, an ambient executable, or a second cleanup implementation.
 
+The `hephaestus-tidy` boundary must resolve to a Hephaestus revision that propagates the inner
+cleanup exit status. Athena checks that the resolved checkout includes commit
+`aa357098e5d72178d248e4188e7f5e5f843cdd3f` before delegation. Athena consumes that status
+transparently; it does not infer success from output. If the resolved checkout does not satisfy
+that contract, stop.
+
 ## Failed approaches
 
 - Do not audit worktrees in Athena. Do not remove worktrees in Athena. These actions duplicate the
@@ -126,7 +137,8 @@ similar name, an ambient executable, or a second cleanup implementation.
 
 Before execution, report the resolved Hephaestus repository, commit SHA, and trust basis. After
 execution starts, preserve the delegated command output and terminal result. Do not add
-Athena-specific worktree classifications or cleanup conclusions.
+Athena-specific worktree classifications or cleanup conclusions. Report the delegated result as-is:
+success conclusions require a zero exit, and a nonzero exit is incomplete cleanup.
 
 ## Attribution
 

package/skills/tidy/scripts/run_tidy.py

@@ -4,15 +4,60 @@
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import os
+import subprocess
 import sys
 from collections.abc import Sequence
 from pathlib import Path
+from typing import TYPE_CHECKING
 
-if __package__ in {None, ""}:
-    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+if TYPE_CHECKING or __package__ not in {None, ""}:
+    from skills._cli import argument_parser, git_read_arguments, git_read_environment
+else:
+    _cli_path = Path(__file__).resolve().parents[2] / "_cli.py"
+    _cli_spec = importlib.util.spec_from_file_location(
+        "athena_installed_cli", _cli_path
+    )
+    if _cli_spec is None or _cli_spec.loader is None:
+        raise RuntimeError(
+            f"The installed Athena CLI helper is unavailable: '{_cli_path}'."
+        )
+    _cli = importlib.util.module_from_spec(_cli_spec)
+    _cli_spec.loader.exec_module(_cli)
+    argument_parser = _cli.argument_parser
+    git_read_arguments = _cli.git_read_arguments
+    git_read_environment = _cli.git_read_environment
 
-from skills._cli import argument_parser
+_REQUIRED_HEPHAESTUS_TIDY_REVISION = "aa357098e5d72178d248e4188e7f5e5f843cdd3f"
+
+
+def _validate_hephaestus_revision(automation_checkout: Path) -> int:
+    """Fail closed when the resolved Hephaestus checkout is older than the fix."""
+    command = [
+        "git",
+        *git_read_arguments(),
+        "-C",
+        str(automation_checkout),
+        "merge-base",
+        "--is-ancestor",
+        _REQUIRED_HEPHAESTUS_TIDY_REVISION,
+        "HEAD",
+    ]
+    try:
+        result = subprocess.run(command, check=False, env=git_read_environment())
+    except FileNotFoundError as error:
+        missing = error.filename or command[0]
+        print(f"The required command is not available: '{missing}'.", file=sys.stderr)
+        return 127
+    if result.returncode != 0:
+        print(
+            "The resolved Hephaestus checkout is stale; it must include "
+            f"commit {_REQUIRED_HEPHAESTUS_TIDY_REVISION}.",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -21,6 +66,9 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument("automation_checkout", type=Path)
     parser.add_argument("arguments", nargs=argparse.REMAINDER)
     parsed = parser.parse_args(raw_arguments)
+    validation_status = _validate_hephaestus_revision(parsed.automation_checkout)
+    if validation_status != 0:
+        return validation_status
     command = [
         "uv",
         "run",