@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/README.md

@@ -1,13 +1,20 @@
 # athena-opencode
 
-[Athena](https://github.com/HomericIntelligence/Athena) workflow skills packaged as an
-[opencode](https://opencode.ai) plugin. Installing this plugin places the full canonical skill
-corpus under your opencode configuration directory, where opencode discovers and loads it natively.
+[Athena](https://github.com/HomericIntelligence/Athena) packages its workflow skills as an
+[opencode](https://opencode.ai) plugin. The plugin contains the full canonical skill corpus. It puts
+the corpus in the opencode configuration directory. Opencode finds and loads the corpus there.
+
+Athena uses the
+[ASD-STE100 technical-English policy](skills/TECHNICAL_ENGLISH.md)
+for its English technical prose.
 
 ## Install
 
-Add the package to the `plugin` array of your opencode configuration
-(`~/.config/opencode/opencode.json` or a project `opencode.json`):
+Add the package to the `plugin` array in the opencode configuration. Use one of these configuration
+files:
+
+- `~/.config/opencode/opencode.json`; or
+- a project `opencode.json`.
 
 ```json
 {
@@ -16,29 +23,35 @@ Add the package to the `plugin` array of your opencode configuration
 }
 ```
 
-Quit and restart opencode. On startup the plugin copies the bundled `skills/` corpus to:
+Quit opencode. Then, restart opencode. During startup, the plugin copies the bundled `skills/` corpus
+to this location:
 
 ```
 $XDG_CONFIG_HOME/opencode/skills/athena/
 ```
 
-(`~/.config/opencode/skills/athena/` by default.) The plugin only ever writes inside that
-`athena/` namespace; other skills in your configuration are never touched. Each restart refreshes
-the namespace to match the installed plugin version, so upgrading the npm package upgrades the
-skills.
+If `XDG_CONFIG_HOME` does not have a value, the target is
+`~/.config/opencode/skills/athena/`. The plugin writes only in the `athena/` namespace. It does not
+change other skills in your configuration. At each restart, the plugin makes the namespace agree
+with the installed plugin version. Thus, a package update also updates the skills.
 
 ## Use
 
-Invoke skills through opencode's native skill mechanism, for example by asking opencode to use the
-`repo-review`, `pr-review`, or `plan-issue` skill. See the root
-[`README.md`](https://github.com/HomericIntelligence/Athena#readme) for the full skill catalog,
-dependency requirements (Git, Python 3.13, authenticated `gh` for forge routes), and capability
-fallbacks.
+Use the native opencode skill mechanism. For example, ask opencode to use the `repo-review`,
+`pr-review`, or `plan-issue` skill. See the root
+[`README.md`](https://github.com/HomericIntelligence/Athena#readme) for this information:
+
+- the full skill catalog;
+- dependency requirements for Git and Python 3.13;
+- the authenticated GitHub CLI (`gh`) requirement for forge routes; and
+- capability fallbacks.
 
 ## Uninstall
 
-Remove `"@homericintelligence/athena-opencode"` from the `plugin` array, restart opencode, and delete
-`opencode/skills/athena/` from your configuration directory if you want the files gone immediately.
+1. Remove `"@homericintelligence/athena-opencode"` from the `plugin` array.
+2. Restart opencode.
+3. To remove the files immediately, delete `opencode/skills/athena/` from your configuration
+   directory.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homericintelligence/athena-opencode",
-  "version": "0.4.4",
-  "description": "Athena workflow skills packaged as an opencode plugin.",
+  "version": "0.5.1",
+  "description": "Athena provides workflow skills as an opencode plugin.",
   "license": "BSD-3-Clause",
   "type": "module",
   "main": "plugin.js",

package/plugin.js

@@ -1,4 +1,11 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,7 +33,7 @@ export function syncSkills() {
   const target = installTarget();
   if (!existsSync(join(source, "_cli.py"))) {
     throw new Error(
-      `Athena skill corpus is missing next to plugin.js: ${source}`,
+      `The plugin cannot find the Athena skills next to plugin.js: '${source}'.`,
     );
   }
   mkdirSync(dirname(target), { recursive: true });
@@ -39,7 +46,9 @@ async function athenaPlugin() {
   try {
     syncSkills();
   } catch (error) {
-    console.warn(`[athena-opencode] skill installation failed: ${error}`);
+    console.warn(
+      `[athena-opencode] The plugin could not install the skills: ${error}`,
+    );
   }
   return {};
 }
@@ -47,8 +56,14 @@ async function athenaPlugin() {
 export default athenaPlugin;
 
 export function bundledSkillNames() {
-  return readdirSync(bundledSkillsRoot(), { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+  const root = bundledSkillsRoot();
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        existsSync(join(root, entry.name, "SKILL.md")) &&
+        statSync(join(root, entry.name, "SKILL.md")).isFile(),
+    )
     .map((entry) => entry.name)
     .sort();
 }

package/skills/TECHNICAL_ENGLISH.md

@@ -0,0 +1,78 @@
+# ASD-STE100 technical-English policy
+
+All Athena English technical prose must follow
+[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/). This requirement applies to
+skills, agent directions, public documents, user messages that a skill produces, and text in a user
+interface.
+
+The literal text that this policy identifies does not have to obey it.
+
+## Authority
+
+Use the current official issue of ASD-STE100 as the authority. Request a copy from the
+[official download page](https://www.asd-ste100.org/STE_downloads.html).
+
+This repository policy does not copy or replace the standard. It does not replace approved
+training. Repository checks can find Markdown errors, broken package contracts, and some style
+risks. The checks do not certify conformance to ASD-STE100.
+
+## Required method
+
+Use these steps when you write or change technical prose:
+
+1. Read the applicable technical source before you write.
+2. Use approved words with their approved meanings and parts of speech.
+3. Use a technical noun or a technical verb when the approved dictionary has no necessary term.
+4. Use one term for one meaning.
+5. Do not use a different synonym for the same item or action.
+6. Use American English spelling unless an exact external name uses a different spelling.
+7. Use active voice when you know the actor.
+8. Use the imperative form for a direct instruction.
+9. Put a condition before the related action when the reader must know the condition first.
+10. Give one primary instruction in each numbered step.
+11. Keep sentences short.
+12. Split a sentence when it contains more than one independent idea.
+13. Use a vertical list when it makes complex information easier to identify.
+14. Avoid an `-ing` form when an approved, unambiguous form gives the same meaning.
+15. Define each abbreviation at its first use unless the intended readers always know it.
+16. Keep the technical meaning.
+17. Do not remove a necessary safety, evidence, permission, or failure condition to make a sentence
+    shorter.
+18. Review the result against the current official standard.
+
+## Literal text
+
+Do not change literal text only to make it conform to this policy. Literal text includes:
+
+- programming-language syntax and generated code;
+- commands, options, identifiers, paths, URLs, and API field names;
+- machine-readable markers, schemas, and data values;
+- legal text, licenses, and required notices;
+- attributed quotations; and
+- historical records that must preserve their original text.
+
+A message for a user or an agent is technical prose even when source code contains it. This rule
+applies to command help, error messages, status messages, prompts, and user-interface labels.
+
+Write the prose around literal text in accordance with ASD-STE100.
+
+Use code formatting or a quotation format to make the literal boundary clear.
+
+## Conflict and verification
+
+Technical accuracy, safety controls, security controls, evidence rules, and higher-authority
+instructions take precedence. If simplified wording changes the required meaning, use these steps:
+
+1. Keep the required meaning.
+2. Rewrite the sentence.
+
+Ask for a technical review when you cannot remove the ambiguity.
+
+If you cannot use the current official standard:
+
+- Apply this policy.
+- Report the verification gap.
+
+Do not state that the text conforms to ASD-STE100.
+
+Do not state that a person or tool certified or verified ASD-STE100 conformance.

package/skills/_cli.py

@@ -1,4 +1,4 @@
-"""Shared argparse construction for Athena's executable helpers."""
+"""This module provides shared command-line support for Athena helpers."""
 
 from __future__ import annotations
 
@@ -16,26 +16,29 @@ PLUGIN_ROOT = Path(__file__).resolve().parent.parent
 def run_command(
     arguments: Sequence[str], **kwargs: Any
 ) -> subprocess.CompletedProcess[str]:
-    """Run an external command or identify a missing required capability."""
+    """Run an external command and report a missing required capability."""
     if not arguments:
-        raise RuntimeError("required command is empty")
+        raise RuntimeError("The required command is empty.")
     try:
         check = kwargs.pop("check", False)
         return subprocess.run(arguments, check=check, **kwargs)
     except FileNotFoundError as error:
         command = error.filename or arguments[0]
-        raise RuntimeError(f"required command unavailable: {command}") from error
+        raise RuntimeError(
+            f"The required command is not available: '{command}'."
+        ) from error
 
 
 def git_read_environment() -> dict[str, str]:
-    """Return a hermetic environment for immutable, non-interactive Git reads."""
+    """Return an isolated environment for immutable, non-interactive Git reads."""
     environment = {
         key: value for key, value in os.environ.items() if not key.startswith("GIT_")
     }
     # `--no-replace-objects` does not disable deprecated graft files. Force Git
-    # to read an empty graft source. Strip every inherited GIT_* setting first:
-    # location, object, index, config, attribute, pathspec, and transport
-    # overrides can otherwise redirect or change a supposedly immutable read.
+    # to read an empty graft source. First, remove each inherited `GIT_*`
+    # setting. These settings can redirect or change an immutable read. They
+    # include location, object, index, configuration, attribute, pathspec, and
+    # transport settings.
     environment.update(
         {
             "GIT_ATTR_NOSYSTEM": "1",
@@ -58,7 +61,7 @@ def git_read_arguments() -> tuple[str, ...]:
 
 
 def require_complete_git_history(*, cwd: Path | None = None) -> None:
-    """Reject shallow history before deriving immutable ancestry evidence."""
+    """Reject shallow history before calculation of immutable ancestry evidence."""
     result = run_command(
         ["git", *git_read_arguments(), "rev-parse", "--is-shallow-repository"],
         capture_output=True,
@@ -69,20 +72,21 @@ def require_complete_git_history(*, cwd: Path | None = None) -> None:
     )
     if result.returncode != 0:
         message = (
-            result.stderr.strip() or "git rev-parse --is-shallow-repository failed"
+            result.stderr.strip()
+            or "The git rev-parse --is-shallow-repository command failed."
         )
         raise RuntimeError(message)
     if result.stdout.strip() != "false":
         raise RuntimeError(
-            "immutable review evidence requires a non-shallow repository; "
-            "use a complete source snapshot"
+            "The immutable review evidence needs a non-shallow repository. "
+            "Use a complete source snapshot."
         )
 
 
 def require_unambiguous_git_merge_base(
     base_oid: str, head_oid: str, *, cwd: Path | None = None
 ) -> str:
-    """Return the sole immutable merge base or reject ambiguous topology."""
+    """Return the only immutable merge base or reject an ambiguous history."""
     result = run_command(
         [
             "git",
@@ -99,12 +103,12 @@ def require_unambiguous_git_merge_base(
         check=False,
     )
     if result.returncode != 0:
-        message = result.stderr.strip() or "git merge-base failed"
+        message = result.stderr.strip() or "The git merge-base command failed."
         raise RuntimeError(message)
     merge_bases = result.stdout.splitlines()
     if len(merge_bases) != 1 or not merge_bases[0]:
         raise RuntimeError(
-            "immutable review evidence requires one unambiguous merge base"
+            "The immutable review evidence requires one unambiguous merge base."
         )
     return merge_bases[0]
 
@@ -115,7 +119,9 @@ def plugin_version() -> str:
     document = json.loads(manifest.read_text(encoding="utf-8"))
     version = document.get("version") if isinstance(document, dict) else None
     if not isinstance(version, str):
-        raise TypeError(f"plugin manifest has no string version: {manifest}")
+        raise TypeError(
+            f"The plugin manifest does not contain a string version: '{manifest}'."
+        )
     return version
 
 
@@ -134,7 +140,9 @@ class _PluginVersionAction(argparse.Action):
             version = plugin_version()
         except (OSError, TypeError, json.JSONDecodeError) as error:
             parser.exit(
-                1, f"{parser.prog}: error: cannot read plugin version: {error}\n"
+                1,
+                f"{parser.prog}: error: The tool cannot read the plugin version: "
+                f"{error}\n",
             )
         print(f"{parser.prog} {version}")
         parser.exit(0)
@@ -147,6 +155,6 @@ def argument_parser(*, description: str | None = None) -> argparse.ArgumentParse
         "--version",
         action=_PluginVersionAction,
         nargs=0,
-        help="show the Athena plugin version and exit",
+        help="Show the Athena plugin version and exit.",
     )
     return parser

package/skills/_support/docs/dependency-resolution.md

@@ -0,0 +1,192 @@
+# Required repository resolution
+
+Apply the [ASD-STE100 technical-English policy](../../TECHNICAL_ENGLISH.md) to all English technical prose
+in this document.
+
+**Why:** Athena must use trusted and current knowledge and automation. It must not use a repository
+only because it has a similar name. It must not use a stale checkout or an unverified remote.
+
+## At a glance
+
+During normal resolution, Athena does these steps:
+
+1. It resolves a trusted owner.
+2. It synchronizes an exact checkout.
+3. It binds use to the reported revision.
+
+A trust, authentication, checkout, or update failure stops the dependent skill.
+
+In planning mode, an explicit read-only path can use an existing checkout as a best-effort source.
+This path does not synchronize with the upstream repository. It must do these actions:
+
+- bind use to the current `HEAD`;
+- report the current `HEAD`;
+- report the freshness and trust limits;
+- never substitute a different repository; and
+- never make a durable write.
+
+A skill can impose stricter requirements. The `learn` skill requires a usable checkout before it
+starts discovery or writes a lesson. In planning mode, its discovery path does not create a checkout.
+
+```mermaid
+flowchart LR
+    A["Resolve dependency"] --> B{"Is there an explicit owner?"}
+    B -->|yes| C["Validate override"]
+    B -->|no| D{"Is there a trusted organization fork?"}
+    D -->|yes| E["Use maintained fork"]
+    D -->|no| F["Use canonical upstream"]
+    C --> G["Verify origin and clean checkout"]
+    E --> G
+    F --> G
+    G --> H{"Is this the read-only planning path?"}
+    H -->|yes| I["Inspect existing checkout; bind current HEAD; report limits"]
+    H -->|no| J["Fetch, fast-forward, and bind SHA"]
+    J --> K["Revalidate automatic-fork trust before use"]
+```
+
+## Component details
+
+### Owner selection
+
+For dependency `<Repository>` with environment override `<OWNER_VARIABLE>`, use these steps:
+
+1. If `<OWNER_VARIABLE>` is not empty, select `<value>/<Repository>`.
+
+   - Before you use the owner in a path or command, validate it as a GitHub owner name.
+   - If the explicit override is not valid, report an error.
+   - If the explicit override is not valid, stop.
+   - If the explicit override is not valid, do not use a fallback.
+   - The owner name must meet these requirements:
+
+     - It contains 1 through 39 characters.
+     - It contains only ASCII letters, digits, or single hyphens.
+     - It does not start or end with a hyphen.
+
+2. If `<OWNER_VARIABLE>` is empty, get the current repository owner with this command:
+
+   ```bash
+   gh repo view --json owner --jq .owner.login
+   ```
+
+   Use `<current-owner>/<Repository>` only when all these automatic-fork trust gates pass:
+
+   - The `owner.type` of the current repository is `Organization` and not `User`.
+   - The `viewerPermission` of the authenticated viewer on the current repository is `WRITE` (push),
+     `MAINTAIN`, or `ADMIN`.
+   - GitHub confirms that the candidate is a fork. Its `parent.full_name` must be
+     `HomericIntelligence/<Repository>`.
+   - Athena can resolve and report the candidate repository and the tip SHA of its remote default
+     branch.
+
+3. If no trusted override or automatic fork applies, use `HomericIntelligence/<Repository>`.
+
+Do not automatically select a repository with the same name in these conditions:
+
+- The owner of the current repository is a user.
+- The viewer has read, triage, or no permission.
+- Athena cannot prove canonical ancestry.
+
+Use repository metadata to make the fork decision. Do not use only the repository name:
+
+```bash
+current_owner=$(gh repo view --json owner --jq '.owner.login')
+gh api "repos/${current_owner}/<Repository>" \
+  --jq '.fork == true and .parent.full_name == "HomericIntelligence/<Repository>"'
+```
+
+Only the literal result `true` passes the ancestry check. Use structured application programming
+interface (API) output. Quote each derived value. Resolve these values:
+
+- the `owner.type` of the current repository;
+- the `viewerPermission` of the authenticated viewer;
+- the `.default_branch` of the candidate; and
+- the exact tip `.sha` of that branch.
+
+The fork can contain modified content after all automatic trust gates pass. If the same-owner
+candidate is missing or not eligible, use the canonical upstream repository. If an API or
+authentication error prevents a trustworthy decision, treat the error as fatal and stop.
+
+An explicit owner override is an explicit trust decision. It can select custom fork content without
+the organization and viewer-permission gate. Before you use a resolved dependency, report this
+information:
+
+- the exact repository;
+- the commit SHA; and
+- the trust basis: `explicit override`, `maintained organization fork`, or `canonical upstream`.
+
+### Dependency map
+
+| Purpose | Repository | Override | Checkout |
+| --- | --- | --- | --- |
+| Knowledge | `Mnemosyne` | `HOMERIC_INTELLIGENCE_MNEMOSYNE_OWNER` | `$HOME/.agent_brain/knowledge` |
+| Automation | `Hephaestus` | `HOMERIC_INTELLIGENCE_HEPHAESTUS_OWNER` | `$HOME/.agent_brain/automation` |
+
+### Checkout and revalidation
+
+Normal resolution requires these capabilities:
+
+- authenticated GitHub CLI (`gh`);
+- `git`; and
+- network access.
+
+Create `$HOME/.agent_brain` when it is necessary. If the checkout is absent, clone the resolved
+repository. For an existing checkout, do these checks and actions:
+
+- Require `origin` to identify the resolved `owner/repository`.
+- Do not overwrite local changes or silently change the remote.
+- Fetch `origin`.
+- Resolve the default branch of `origin`.
+- Fast-forward that branch.
+- Report the resolved repository and commit SHA.
+
+For an automatically selected same-owner fork, repeat the trust checks immediately before use. Do
+this before you read knowledge or execute automation. Re-query these values:
+
+- the Organization owner of the current repository;
+- the permission of the viewer;
+- the `parent.full_name` of the candidate;
+- the resolved repository identity;
+- the default branch; and
+- the tip SHA.
+
+Require these values to agree with the reported trust decision. Require the checked-out commit to
+agree with the re-queried tip SHA. Stop if a value does not agree. This check closes the race between
+resolution and use.
+
+### Read-only local best effort
+
+Use this exception only for a read-only planning path or a `learn` discovery path. The path can
+inspect an existing checkout. It can bind use to the current `HEAD` without these actions:
+
+- clone;
+- fetch;
+- fast-forward; or
+- revalidation of an automatic fork.
+
+Report this information:
+
+- the checkout;
+- the revision;
+- the trust basis or trust uncertainty; and
+- the freshness limit.
+
+If the checkout is missing or inspection fails, stop the dependent knowledge retrieval. The caller
+can continue its primary plan only when its skill contract permits planning without guidance. The
+`learn` skill does not permit this fallback. It blocks without an existing usable checkout.
+
+For normal execution and the `learn` delivery boundary, these conditions are fatal:
+
+- an authentication failure;
+- a missing repository;
+- a fork relationship that is not valid;
+- an unexpected `origin`;
+- conflicting local state;
+- a clone failure;
+- a fetch failure; or
+- a fast-forward failure.
+
+The read-only local exception never permits pull-request creation before upstream synchronization.
+
+Mnemosyne writes use isolated worktrees and always end in a pull request. Athena reads or executes
+Hephaestus from its canonical checkout. Athena never edits Hephaestus unless the user explicitly asks
+for a Hephaestus change.

package/skills/_support/docs/policies/development.md

@@ -0,0 +1,117 @@
+# Development and delivery policy
+
+## Technical English
+
+Apply the [ASD-STE100 technical-English policy](../../../TECHNICAL_ENGLISH.md) to all English technical
+prose in this document. Do not remove or weaken a technical, safety, security, evidence, permission,
+or failure requirement to make text shorter.
+
+## Git
+
+- `main` is protected. Send all changes through short-lived feature branches and pull requests.
+- Use Conventional Commit subjects.
+- Sign each commit cryptographically. Include a Developer Certificate of Origin (DCO)
+  `Signed-off-by` trailer.
+- Do not use `--no-verify`.
+- Do not use an unguarded force-push.
+- If a workflow requires rewritten history, you can update a feature branch with
+  `--force-with-lease --force-if-includes`.
+- Never force-push a protected branch or a default branch.
+- Stage intentional paths. Do not include unrelated user changes in a commit.
+- Accepted architecture decision records (ADRs) are append-only. To change an accepted decision,
+  write a new ADR that links to the prior decision.
+
+## Pull requests
+
+- Target `main`.
+- Keep the scope aligned with one issue or one coherent maintenance objective.
+- If an issue tracks the work, put `Closes #N` on its own line in the body.
+- Run required checks against the current head revision. The checks must be successful, current, and
+  not incorrectly skipped.
+- Before auto-merge or merge, get an independent strict review.
+- Use a merge method that the repository supports. Do not guess or impose an organization-wide
+  fallback.
+
+## Safety
+
+- Never commit credentials, tokens, `.env` files, private keys, or personal data.
+- Get explicit user authority before a filesystem-destructive command or before you discard changes.
+- Never use `git reset --hard`.
+- You can use constructive Git, GitHub command-line interface (CLI), and Hephaestus operations when
+  both conditions are true:
+
+  - The requested task permits the operation.
+  - The repository contract permits the operation.
+
+- For branch and worktree cleanup, prefer guarded Hephaestus tools.
+- Preserve unrelated worktree changes. If safe isolation is not possible, stop.
+- Never bypass a failed validation, security, review, or policy gate.
+- Apply the canonical [engineering principles](../principles/README.md) as decision rules. Select only
+  the principles that apply to the change. For routine Athena development, use these groups:
+
+  - Bind scope and design choices to [P001](../principles/README.md#p001),
+    [P002](../principles/README.md#p002), and [P010](../principles/README.md#p010).
+  - Keep one authority and one state owner under [P003](../principles/README.md#p003) and
+    [P078](../principles/README.md#p078).
+  - Follow the established architecture and contracts under
+    [P004](../principles/README.md#p004), [P005](../principles/README.md#p005),
+    [P006](../principles/README.md#p006), [P015](../principles/README.md#p015), and
+    [P019](../principles/README.md#p019).
+  - Verify changed behavior under [P022](../principles/README.md#p022),
+    [P026](../principles/README.md#p026), [P064](../principles/README.md#p064),
+    [P065](../principles/README.md#p065), and [P091](../principles/README.md#p091).
+
+- Repository, security, evidence, user, and system contracts take precedence over a general
+  principle. A principle never grants authority. It never expands the requested scope or weakens a
+  stricter safety or validation rule.
+
+## Durable-artifact and test policy
+
+- Create or change an artifact only when it has one or more of these direct purposes:
+
+  - implement the repository product;
+  - verify the repository product;
+  - distribute the repository product;
+  - operate the repository product;
+  - secure the repository product; or
+  - explain the repository product.
+
+- Do not generate documents or unrelated files only to make the repository appear complete.
+- Do not introduce these manually maintained artifacts when source discovery or an existing
+  authority can give the information:
+
+  - changelogs;
+  - generated documents;
+  - duplicated catalogs;
+  - registries;
+  - inventories;
+  - counts; or
+  - file lists.
+
+- Add such an artifact only when a current consumer requires it. The owner and update method must be
+  explicit.
+- Tests must verify computable behavior, data contracts, security properties, or executable artifact
+  structure.
+- Do not test prose wording, headings, paragraph presence, document counts, or duplicated text
+  strings.
+- Markdown lint and link checks can verify document syntax and link resolution. They must not freeze
+  editorial content.
+- Prefer stable public outcomes to these types of assertions:
+
+  - implementation-detail assertions;
+  - snapshot assertions;
+  - timing assertions;
+  - network assertions;
+  - ambient-environment assertions; or
+  - ordering assertions.
+
+- A test must fail for the product defect that it claims to find.
+- For document-only changes, use the existing Markdown lint and link checks. Do not create a new test
+  harness or application code only to test documents.
+
+## Human review routing
+
+Human review and Code Owner review are optional for Athena changes. They are not required.
+`CODEOWNERS` records advisory ownership. The baseline ruleset does not require an approval count or a
+Code Owner approval. Workflow, release, dependency, and security-control changes remain subject to
+the required checks and requested-scope boundaries of the repository.