@homericintelligence/athena-opencode 0.5.1 → 0.5.2

package/skills/realign/references/control-flow-and-errors.md

@@ -0,0 +1,344 @@
+# Control flow and error catalog
+
+Use this catalog with the
+[errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability) and the
+[language-routing contract](../../_support/docs/review/language-routing.md). Apply the error model of the
+target language. Exceptions, error values, result types, status values, and cancellation signals can
+carry the same policy concerns.
+
+Handle a failure at the nearest responsible boundary. This is the nearest boundary that has enough
+policy context to complete recovery, cleanup, compensation, bounded retry, redaction, translation,
+termination, or another specified outcome. It is not always the local function. It is not always the
+outermost boundary. If a layer cannot complete the outcome, preserve the cause and propagate the
+failure.
+
+Do not infer a defect from branch count, nesting depth, exception count, or a generated diagnostic.
+Confirm a reachable behavior or architecture effect. Route the lead to `retain` when the evidence
+does not support a change.
+
+## Branch or guard structure that hides a state model
+
+- **Signal:** Nested conditions, repeated predicates, Boolean flags, early exits, and switch branches
+  encode combinations of the same domain state. Different branches perform the same transition or
+  use incompatible transition rules.
+- **Required evidence:** Enumerate the reachable states and transitions. Identify repeated decisions,
+  unreachable paths, or inconsistent outcomes. Bind them to a contract, caller, or test. A complexity
+  score or nesting threshold is not sufficient evidence.
+- **Impact:** State the incorrect transition, hidden invariant, duplicate policy, or maintenance
+  action that the flow causes.
+- **Legitimate counterexample:** Retain explicit branches when they are the clearest form of a small
+  decision. Retain a decision table or state machine when the domain has necessary states and the
+  repository makes their transitions explicit.
+- **Smallest safe correction:** Name the state or predicate one time at its owner. Use an existing
+  state type, decision table, or guard form when it makes the transitions explicit. Do not add a
+  framework only to reduce nesting.
+- **Validation:** Test each applicable transition, boundary value, and invalid state. Confirm that the
+  refactor starts from a green behavior baseline.
+- **Routing owner:** Use `realign` for state or policy restructuring. Use `simplify` when branch
+  deletion is the complete evidence-backed correction. Use `systematic-debugging` first when a
+  branch has a current behavior defect.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P020](../../_support/docs/principles/README.md#p020),
+  [P070](../../_support/docs/principles/README.md#p070),
+  [P072](../../_support/docs/principles/README.md#p072), and
+  [P075](../../_support/docs/principles/README.md#p075).
+- **Sources:** [Athena behavior-first testing contract](../../_support/docs/review/behavior-first-testing.md),
+  [AISlop rule catalog](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md), and
+  [a practitioner discussion of generated nesting and broad catches](https://news.ycombinator.com/item?id=45535937).
+
+## Duplicate validation or validation at the wrong boundary
+
+- **Signal:** Core functions repeatedly check a representation that an earlier trusted boundary
+  already validated. Parsing, normalization, validation, and operation occur in many layers. An
+  external or trust boundary has no validation, while downstream code adds defensive guards.
+- **Required evidence:** Identify the trust and construction boundaries. Trace the value from its
+  untrusted form to its trusted form. Show the duplicated invariant or the path that can bypass
+  validation. Similar checks are not sufficient evidence when they enforce different contracts.
+- **Impact:** State the inconsistent rejection, missing protection, branch growth, type erosion, or
+  duplicate maintenance that the placement causes.
+- **Legitimate counterexample:** Retain independent checks for different trust boundaries. Retain a
+  check near a destructive operation when state can change after initial validation. Retain defense
+  in depth when the controls do not share one failure cause.
+- **Smallest safe correction:** Parse and validate at each applicable trust boundary. Pass a trusted
+  representation to core logic. Remove downstream checks only after all bypass paths and time-of-use
+  changes are excluded.
+- **Validation:** Test malformed, boundary, and valid inputs at the public boundary. Test direct
+  internal entry points when they are supported contracts. Run the repository-selected type and
+  schema checks.
+- **Routing owner:** Use `realign` to move or strengthen a validation boundary. Use `simplify` for
+  duplicate checks only after evidence proves that the authoritative boundary is complete.
+- **Applicable principles:** [P011](../../_support/docs/principles/README.md#p011),
+  [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P015](../../_support/docs/principles/README.md#p015),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P072](../../_support/docs/principles/README.md#p072),
+  [P053](../../_support/docs/principles/README.md#p053),
+  [P054](../../_support/docs/principles/README.md#p054), and
+  [P076](../../_support/docs/principles/README.md#p076).
+- **Sources:** [Athena architecture and simplicity profile](../../_support/docs/review/common.md#architecture-and-simplicity),
+  [GitHub guidance for review of generated code](https://docs.github.com/en/copilot/tutorials/review-ai-generated-code),
+  and [AISlop rule catalog](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md).
+
+## Hidden default or semantic fallback
+
+- **Signal:** A catch, error branch, null-coalescing path, or feature fallback returns an empty,
+  cached, permissive, or default result without a public contract for that result. The caller cannot
+  distinguish success from degraded operation.
+- **Required evidence:** Trace the reachable failure to the fallback and its consumers. Identify the
+  stated result contract, security state, freshness rule, and observability requirement. A default
+  value is not sufficient evidence when it is part of the documented contract.
+- **Impact:** State the incorrect success signal, stale result, denied diagnostic, weakened security,
+  or state divergence that the fallback causes.
+- **Legitimate counterexample:** Retain a documented graceful-degradation mode when it keeps correct
+  and secure operation. Retain a fail-safe outer boundary when its contract requires continued
+  service, records sufficient evidence, and puts state in a safe condition.
+- **Smallest safe correction:** Make the degraded outcome explicit or propagate the failure to the
+  nearest responsible boundary. Remove a fallback only when all consumers can handle the corrected
+  contract.
+- **Validation:** Test dependency failure, stale data, invalid input, and degraded operation that
+  apply. Verify the public status, error, state, and structured diagnostic.
+- **Routing owner:** Use `realign` for fallback-policy or boundary repair. Use `simplify` only when
+  the fallback is dead or redundant and safe deletion is complete.
+- **Applicable principles:** [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P031](../../_support/docs/principles/README.md#p031),
+  [P032](../../_support/docs/principles/README.md#p032),
+  [P033](../../_support/docs/principles/README.md#p033),
+  [P034](../../_support/docs/principles/README.md#p034), and
+  [P036](../../_support/docs/principles/README.md#p036).
+- **Sources:** [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability),
+  [AISlop rule catalog](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md), and
+  [a reproduced exception-handling regression report](https://github.com/anthropics/claude-code/issues/40355).
+
+## Error handling without policy ownership
+
+- **Signal:** A local function catches or converts all failures but cannot recover, retry, compensate,
+  redact, translate a public contract, or stop correctly. An outer boundary handles unrelated
+  failures with one outcome. Intermediate layers repeatedly change the error form.
+- **Required evidence:** Map the initial cause through each boundary. For every handler, identify its
+  policy decision and ability to complete that decision. Show the consumer contract and state after
+  failure. Catch width alone is not sufficient evidence.
+- **Impact:** State the lost cause, incorrect response, duplicate handling, unsafe continuation, or
+  policy coupling that the boundary causes.
+- **Legitimate counterexample:** Retain local handling when it completes a specified recovery or
+  cleanup policy. Retain an outer safety boundary when it must isolate one request, task, or event and
+  it records the failure before safe continuation.
+- **Smallest safe correction:** Keep handling at the nearest boundary that owns the outcome. If the
+  current layer has no outcome to select, preserve type, cause, and useful context, and propagate one
+  time. Do not move all handling to the outermost boundary as a universal rule.
+- **Validation:** Test each public error outcome, recovery path, cleanup path, and failure state.
+  Verify language-specific cause chaining or error wrapping. Confirm that one policy owner handles
+  each failure.
+- **Routing owner:** Use `realign` for error-boundary repair. Use `systematic-debugging` before repair
+  when evidence shows an active failure. Route a redundant catch that can be deleted without another
+  structural change to `simplify`.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P031](../../_support/docs/principles/README.md#p031),
+  [P032](../../_support/docs/principles/README.md#p032).
+- **Sources:** [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability),
+  [Exception Handling Bugs in Python](https://doi.org/10.1016/j.infsof.2026.108264), and
+  [a practitioner discussion of blanket catches](https://news.ycombinator.com/item?id=45535937).
+
+## Duplicate handling or lost causal information
+
+- **Signal:** Code catches, logs, and throws the same failure without a policy decision. It converts
+  all causes to one string, Boolean, null value, or generic status. Several layers emit the same
+  failure as separate incidents. A replacement error omits the initial cause.
+- **Required evidence:** Trace error identity, cause, context, and diagnostics from source to the
+  responsible boundary. Identify the information that a caller or operator needs. Similar log
+  messages alone are not sufficient evidence.
+- **Impact:** State the incorrect classification, duplicate alert, lost diagnosis, false success, or
+  public-contract error that results.
+- **Legitimate counterexample:** Retain a local span event, metric, or context addition when it has a
+  distinct observability purpose and keeps correlation. Retain public translation that intentionally
+  redacts sensitive detail while the internal cause remains available to the authorized operator.
+- **Smallest safe correction:** Select one policy owner for handling. Preserve the language-specific
+  causal chain when context or a public error type is added. Emit one operator incident with stable
+  correlation. Do not expose secrets to preserve diagnostics.
+- **Validation:** Test error classification and public translation. Inspect the cause chain and
+  structured diagnostics. Confirm that failure telemetry is neither absent nor duplicated.
+- **Routing owner:** Use `realign` for error-contract or observability ownership changes. Use
+  `simplify` when removal of an unchanged catch or duplicate log is the complete safe correction.
+- **Applicable principles:** [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P031](../../_support/docs/principles/README.md#p031),
+  [P032](../../_support/docs/principles/README.md#p032), and
+  [P047](../../_support/docs/principles/README.md#p047).
+- **Sources:** [Athena language-routing contract](../../_support/docs/review/language-routing.md),
+  [AISlop rule catalog](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md), and
+  [a reproduced exception-handling regression report](https://github.com/anthropics/claude-code/issues/40355).
+
+## Unsafe or duplicate retry policy
+
+- **Signal:** A loop retries all failures, has no finite budget, or repeats a non-idempotent effect.
+  Several layers retry the same operation. Timeouts cause retries that continue after the caller has
+  stopped. A circuit breaker or backoff is added without dependency-failure evidence.
+- **Required evidence:** Identify the retry owner, transient-failure classification, total deadline,
+  attempt budget, idempotency or reconciliation mechanism, and retries in lower or higher layers.
+  Show the duplicate effect or availability requirement. The presence or absence of retry code alone
+  is not sufficient evidence.
+- **Impact:** State the duplicate side effect, request amplification, delayed failure, capacity loss,
+  or unmet availability contract.
+- **Legitimate counterexample:** Retain a repository or client-library retry when it has the complete
+  policy, obeys the caller deadline, and makes repeated effects safe. Do not require retry for a
+  permanent failure or an operation that cannot repeat safely.
+- **Smallest safe correction:** Give one responsible boundary the retry policy. Make the operation
+  idempotent or reconcilable before retry. Classify transient failures and use a finite budget within
+  the caller deadline. Add backoff or a circuit breaker only when operation evidence requires it.
+- **Validation:** Use controlled failure injection. Test the maximum attempt count, permanent
+  failure, deadline, cancellation, repeated side effects, and success after a transient failure.
+- **Routing owner:** Use `realign`. Use `systematic-debugging` first for a reproduced retry defect.
+  Use `simplify` when an extra retry layer can be removed with no other contract change.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P037](../../_support/docs/principles/README.md#p037),
+  [P038](../../_support/docs/principles/README.md#p038), and
+  [P070](../../_support/docs/principles/README.md#p070).
+- **Sources:** [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability)
+  and [AWS guidance for timeouts and retries](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/).
+
+## Missing or broken timeout and cancellation propagation
+
+- **Signal:** An external operation, lock, queue wait, or child task has no applicable bound. Code
+  catches or replaces cancellation. A child operation outlives its owner. A timeout is reported as
+  success or as an unrelated failure.
+- **Required evidence:** Identify the lifecycle owner, caller deadline, cancellation source, cleanup
+  duties, and result contract. Show a reachable unbounded wait, orphaned operation, or lost
+  cancellation. A function without a timeout parameter is not sufficient evidence.
+- **Impact:** State the resource leak, capacity loss, stale write, delayed shutdown, or incorrect
+  caller outcome.
+- **Legitimate counterexample:** Retain a process-lifetime task, local bounded computation, or
+  framework-managed deadline when its owner and termination contract are explicit. Retain a cleanup
+  operation after cancellation when it has its own safe bound.
+- **Smallest safe correction:** Propagate the existing cancellation or deadline through the supported
+  interface. Give child work the owner lifecycle. On cancellation, stop new work and release owned
+  resources. Preserve the cancellation outcome.
+- **Validation:** Use controlled time and explicit synchronization. Test cancellation before start,
+  during work, and during cleanup. Test deadline expiry and shutdown. Do not use a wall-clock sleep
+  as the only proof.
+- **Routing owner:** Use `realign`. Use `systematic-debugging` first when the repository has a
+  reproduced hang or orphaned task. Use `simplify` only for a proven unused timeout wrapper.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P039](../../_support/docs/principles/README.md#p039),
+  [P070](../../_support/docs/principles/README.md#p070), and
+  [P082](../../_support/docs/principles/README.md#p082).
+- **Sources:** [Athena behavior-first testing contract](../../_support/docs/review/behavior-first-testing.md),
+  [Athena language-routing contract](../../_support/docs/review/language-routing.md), and
+  [AWS guidance for timeouts and retries](https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/).
+
+## Partial state change without atomicity or compensation
+
+- **Signal:** One logical operation writes multiple state owners and can stop between writes. A catch
+  continues after partial progress without a state contract. Compensation is best-effort but has no
+  durable progress, idempotency, or reconciliation rule.
+- **Required evidence:** Identify the invariant, commit boundaries, irreversible step, each failure
+  point, and state after interruption. Show that one transaction is possible or that the distributed
+  workflow needs compensation. Multiple writes are not sufficient evidence when partial progress is
+  the documented state.
+- **Impact:** State the lost update, duplicate effect, unrecoverable state, incorrect resume, or
+  operator action that can result.
+- **Legitimate counterexample:** Retain an eventually consistent or resumable workflow when progress,
+  reconciliation, idempotency, and operator recovery are explicit and tested. Retain independent
+  writes when they do not share an invariant.
+- **Smallest safe correction:** Use one existing transaction when all changes share its boundary. If
+  one transaction is not possible, record durable progress and define idempotent compensation or
+  roll-forward. Put the irreversible action after applicable validation and reversible work.
+- **Validation:** Inject a failure at each material step. Test retry, compensation, resume, duplicate
+  delivery, and rollback or roll-forward. Verify the invariant after each outcome.
+- **Routing owner:** Use `realign`. Use `systematic-debugging` first for reproduced data loss or state
+  corruption. A dead rollback path can use `simplify` only after the replacement recovery contract is
+  proved.
+- **Applicable principles:** [P011](../../_support/docs/principles/README.md#p011),
+  [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P021](../../_support/docs/principles/README.md#p021),
+  [P044](../../_support/docs/principles/README.md#p044),
+  [P045](../../_support/docs/principles/README.md#p045),
+  [P046](../../_support/docs/principles/README.md#p046),
+  [P070](../../_support/docs/principles/README.md#p070), and
+  [P083](../../_support/docs/principles/README.md#p083).
+- **Sources:** [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability)
+  and [Microsoft compensating-transaction guidance](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction).
+
+## Unclear resource or task lifetime
+
+- **Signal:** A file, connection, lock, transaction, subscription, temporary file, child process, or
+  asynchronous task has no clear owner. Cleanup occurs only on success. Cleanup failure replaces the
+  initial failure without an explicit policy. A detached task has no result consumer.
+- **Required evidence:** Trace acquisition, ownership transfer, use, release, and all failure exits.
+  Identify the repository or language lifetime convention. Show a reachable leak, deadlock, orphan,
+  lost failure, or invalid cleanup order. Manual cleanup alone is not sufficient evidence.
+- **Impact:** State the resource exhaustion, blocked progress, data loss, duplicate work, or lost
+  diagnostic that can result.
+- **Legitimate counterexample:** Retain a process-lifetime pool, framework-owned resource, or detached
+  operation when its owner, shutdown, failure, and capacity contracts are explicit. Retain explicit
+  cleanup when the language does not supply a safer construct.
+- **Smallest safe correction:** Give the resource one owner. Use the repository's existing scoped
+  lifetime mechanism. Release resources on every applicable exit. Preserve the initial cause when
+  cleanup also fails, according to the public error policy.
+- **Validation:** Test success, operation failure, cleanup failure, cancellation, and repeated use.
+  Use repository tools that can detect leaks, races, or unreleased locks when the execution boundary
+  permits them.
+- **Routing owner:** Use `realign`. Use `systematic-debugging` first for a reproduced leak, race, or
+  deadlock. Use `simplify` when an unused resource layer can be removed safely.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P029](../../_support/docs/principles/README.md#p029),
+  [P030](../../_support/docs/principles/README.md#p030),
+  [P032](../../_support/docs/principles/README.md#p032), and
+  [P079](../../_support/docs/principles/README.md#p079).
+- **Sources:** [Athena language-routing contract](../../_support/docs/review/language-routing.md),
+  [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability), and
+  [Exception Handling Bugs in Python](https://doi.org/10.1016/j.infsof.2026.108264).
+
+## Detached or uncoordinated concurrent work
+
+- **Signal:** Code starts parallel work without a measured need, shared-state contract, result owner,
+  sibling-failure policy, cancellation rule, or capacity bound. One task failure is ignored while
+  other tasks continue to change state.
+- **Required evidence:** Identify the concurrency requirement, task owner, shared state,
+  synchronization, maximum work, failure aggregation, and cancellation path. Show a reachable race,
+  orphan, duplicate effect, or resource growth. Parallel syntax alone is not sufficient evidence.
+- **Impact:** State the incorrect result, state race, failure loss, shutdown delay, or capacity
+  problem.
+- **Legitimate counterexample:** Retain repository-standard structured concurrency or a supervised
+  background task when ownership, failure, cancellation, and resource limits are explicit. Retain
+  concurrency when reproducible measurements show its need.
+- **Smallest safe correction:** Use the existing lifecycle owner and structured concurrency
+  mechanism. Collect every result. Define sibling behavior after failure. Propagate cancellation and
+  cap concurrent work. Remove concurrency only when behavior and measured requirements permit it.
+- **Validation:** Use deterministic synchronization and race detection when available. Test one and
+  multiple failures, cancellation, shutdown, capacity, and ordering-independent outcomes.
+- **Routing owner:** Use `realign`. Use `systematic-debugging` first for a reproduced race or lost
+  result. Use `simplify` when unnecessary concurrency can be removed with no behavior change.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P019](../../_support/docs/principles/README.md#p019),
+  [P020](../../_support/docs/principles/README.md#p020),
+  [P070](../../_support/docs/principles/README.md#p070),
+  [P072](../../_support/docs/principles/README.md#p072),
+  [P080](../../_support/docs/principles/README.md#p080), and
+  [P082](../../_support/docs/principles/README.md#p082).
+- **Sources:** [Athena errors and reliability profile](../../_support/docs/review/common.md#errors-and-reliability),
+  [Athena behavior-first testing contract](../../_support/docs/review/behavior-first-testing.md),
+  [Athena language-routing contract](../../_support/docs/review/language-routing.md), and
+  [Notes on structured concurrency](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/).

package/skills/realign/references/tests-dependencies-and-security.md

@@ -0,0 +1,261 @@
+# Tests, dependencies, security, and evidence
+
+Read the [shared review contract](../../_support/docs/review/common.md), the
+[behavior-first testing contract](../../_support/docs/review/behavior-first-testing.md), and the
+[language-routing contract](../../_support/docs/review/language-routing.md) before you use this catalog.
+Apply the [ASD-STE100 technical-English policy](../../TECHNICAL_ENGLISH.md) to the assessment and
+repair output.
+
+Use each pattern as an investigation signal. Do not infer authorship from a pattern. Do not make a
+finding until the required evidence shows an effect on behavior, architecture, security, or
+maintenance. A scanner result, metric, test name, or passing command is not sufficient evidence.
+
+## Test theater, weak oracles, and mock-only proof
+
+- **Signal:** A test asserts mock calls, private call order, snapshots of internal layout, or fixed
+  values without an observable product result. Expected values come from the implementation or the
+  same speculative hypothesis as the change. A snapshot or golden file has no authoritative
+  contract. The product path can be absent or wrong while the test stays green.
+- **Required evidence:** Identify the product contract. Trace the test input through real product
+  code to the assertion. Bind an independent oracle, property, metamorphic relation, canonical
+  implementation, or authoritative example. Show the missing connection between the assertion and
+  the contract. Inspect the substitute boundary, test runner, and applicable callers. Try a bounded
+  falsification or negative control before you trust the oracle.
+- **Impact:** A regression can pass the suite. A refactor can require test changes although product
+  behavior does not change. A self-derived oracle can certify the same incorrect assumption as the
+  implementation.
+- **Legitimate counterexample:** A controlled substitute represents a real external boundary. The
+  test exercises core product code and asserts the observable result or failure contract. An
+  approved snapshot or golden file is itself the public compatibility contract.
+- **Smallest safe correction:** Keep substitutes only at external boundaries. Assert the observable
+  contract. Derive expected results independently from the implementation. Add the smallest
+  falsifying, boundary, or property case that distinguishes the incorrect hypothesis. Remove
+  duplicate implementation assertions only after the behavior test gives equivalent coverage.
+- **Validation:** Run the focused test and confirm that it selects an applicable test. Exercise the
+  product path and the applicable failure path. Confirm that a controlled wrong implementation or
+  counterexample makes the test fail. Use repository-approved mutation testing only when it is
+  already available and proportionate to the risk.
+- **Routing owner:** Use `realign` for test-architecture repair. Use `systematic-debugging` when the
+  test exposes an observed defect. Use `simplify` for proven duplicate or obsolete tests.
+- **Applicable principles:** [P022](../../_support/docs/principles/README.md#p022),
+  [P027](../../_support/docs/principles/README.md#p027),
+  [P028](../../_support/docs/principles/README.md#p028),
+  [P064](../../_support/docs/principles/README.md#p064), and
+  [P067](../../_support/docs/principles/README.md#p067).
+- **Sources:** [Athena behavior-first testing](../../_support/docs/review/behavior-first-testing.md),
+  [Are Coding Agents Generating Over-Mocked Tests? An Empirical Study](https://andrehora.github.io/pub/2026-msr-agents-over-mocked-tests.pdf),
+  [EvalPlus](https://arxiv.org/abs/2305.01210), and
+  [OpenAI Codex issue 40639](https://github.com/openai/codex/issues/40639).
+
+## Asynchronous false-green tests and empty selection
+
+- **Signal:** A test starts asynchronous work but does not await or join it. An exception occurs
+  after the runner reports success. A filtered command selects no tests. A test fixture hides
+  cancellation, timeout, or cleanup behavior.
+- **Required evidence:** Inspect the test signature, scheduler boundary, returned task or promise,
+  runner configuration, and assertion path. Record the selected-test count. Trace asynchronous
+  failures to the runner result.
+- **Impact:** The suite can report success before the behavior finishes. Failure, cancellation, and
+  cleanup regressions can be invisible.
+- **Legitimate counterexample:** A framework-required event handler cannot return an awaitable value,
+  and a separate observable completion contract captures its result and errors.
+- **Smallest safe correction:** Await or join all work that is part of the contract. Replace ambient
+  delays with explicit synchronization. Make failures reach the test runner. Make filtered commands
+  prove that they selected the intended test.
+- **Validation:** Run the focused test with a controlled failure, timeout, and cancellation when
+  these paths apply. Confirm deterministic completion and a nonzero applicable-test count.
+- **Routing owner:** Use `realign` for test-lifecycle repair. Use `systematic-debugging` for a
+  reproduced product defect.
+- **Applicable principles:** [P022](../../_support/docs/principles/README.md#p022),
+  [P027](../../_support/docs/principles/README.md#p027),
+  [P028](../../_support/docs/principles/README.md#p028),
+  [P064](../../_support/docs/principles/README.md#p064), and
+  [P065](../../_support/docs/principles/README.md#p065).
+- **Sources:** [Athena behavior-first testing](../../_support/docs/review/behavior-first-testing.md),
+  the [AISlop 0.16.0 rules reference](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md),
+  and [Unit Testing Asynchronous Code](https://learn.microsoft.com/en-us/archive/msdn-magazine/2014/november/async-programming-unit-testing-asynchronous-code).
+
+## Weakened validation gates
+
+- **Signal:** A change skips, deletes, disables, or marks an applicable test as an expected failure.
+  It lowers a threshold, adds a silent continuation, excludes an applicable path, or suppresses a
+  diagnostic without an approved exception.
+- **Required evidence:** Bind the gate definition, repository policy, current result, change history,
+  and affected requirement. Show that the change reduces applicable coverage or changes a failure
+  into success. Distinguish a pre-existing failure from a new regression.
+- **Impact:** Continuous integration (CI) can accept a defect or a policy violation. A passing badge
+  can give false confidence.
+- **Legitimate counterexample:** Evidence proves that a test or check is obsolete, inapplicable, or
+  replaced with equal or stronger coverage. An authoritative process records a narrow exception with
+  an owner and an end condition.
+- **Smallest safe correction:** Correct the product or gate cause. Restore the applicable check. If
+  the contract changed, replace the old check with a behavior test that traces to the new contract.
+- **Validation:** Run the focused check and all required repository gates. Record the command,
+  revision, environment, exit status, and unedited output.
+- **Routing owner:** Use `realign` for validation-architecture repair. Use `simplify` only after
+  evidence proves that a gate artifact is obsolete. Require qualified review when the gate protects
+  security or availability.
+- **Applicable principles:** [P063](../../_support/docs/principles/README.md#p063),
+  [P064](../../_support/docs/principles/README.md#p064),
+  [P065](../../_support/docs/principles/README.md#p065),
+  [P067](../../_support/docs/principles/README.md#p067),
+  [P068](../../_support/docs/principles/README.md#p068),
+  [P069](../../_support/docs/principles/README.md#p069), and
+  [P070](../../_support/docs/principles/README.md#p070).
+- **Sources:** [GitHub guidance for review of AI-generated code](https://docs.github.com/en/copilot/tutorials/review-ai-generated-code).
+
+## Fictional APIs, dependencies, and missed reuse
+
+- **Signal:** Code imports an undeclared or unresolved package. It calls a symbol that the bound
+  dependency version does not provide. It adds a package or wrapper although the repository,
+  language, framework, or standard library already owns the capability.
+- **Required evidence:** Inspect manifests, locks, generated sources, package resolution, the exact
+  dependency version, authoritative API documentation, current repository mechanisms, and runtime
+  consumers. Confirm that dynamic loading or generation does not supply the symbol.
+- **Impact:** Builds or runtime paths can fail. A new package can add maintenance, license, security,
+  and supply-chain work. Duplicate mechanisms can cause architecture drift.
+- **Legitimate counterexample:** The import is an intentional optional peer, plug-in, generated
+  surface, platform branch, or vendored capability with a documented loading and validation contract.
+- **Smallest safe correction:** Use the existing narrow mechanism when it meets the requirement.
+  Correct the API call to the bound version. Add a dependency only when a current requirement and its
+  supply-chain evidence make that addition necessary.
+- **Validation:** Resolve and build from the bound lockfile in an authorized isolated environment.
+  Exercise the reachable behavior. Verify that no stale import, symbol, or wrapper remains.
+- **Routing owner:** Use `simplify` for an unused dependency or a safely removable duplicate. Use `realign`
+  for dependency-direction, ownership, or interface repair. Use `systematic-debugging` for a
+  reproduced behavior defect.
+- **Applicable principles:** [P012](../../_support/docs/principles/README.md#p012),
+  [P015](../../_support/docs/principles/README.md#p015),
+  [P057](../../_support/docs/principles/README.md#p057), and
+  [P074](../../_support/docs/principles/README.md#p074).
+- **Sources:** [GitHub guidance for review of AI-generated code](https://docs.github.com/en/copilot/tutorials/review-ai-generated-code)
+  and [We Have a Package for You!](https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen).
+
+## Dependency trust and provenance
+
+- **Signal:** A change adds or updates a dependency, uses a mutable source reference, leaves a lock
+  mismatch, trusts a package name as identity, enables an install-time script, or adds permissions
+  and transitive dependencies without a stated need.
+- **Required evidence:** Bind the package identity, source, version, lock entry, checksum or signature,
+  provenance, license, maintainer status, advisories, lifecycle scripts, permissions, transitive
+  graph, and the current requirement. Inspect repository dependency policy.
+- **Impact:** The change can execute untrusted code, introduce a vulnerable or deceptive package,
+  expand privileges, or create an unmaintained build input.
+- **Legitimate counterexample:** Repository policy already approves the exact pinned artifact. The
+  dependency is necessary, its provenance is verified, its authority is bounded, and no existing
+  mechanism meets the requirement.
+- **Smallest safe correction:** Remove or replace an unnecessary dependency. Otherwise, pin and lock
+  the approved artifact. Keep provenance and integrity evidence. Disable unnecessary lifecycle
+  behavior and permissions. Do not install a package under `realign` authority alone.
+- **Validation:** Use repository-approved software composition analysis and lock verification. In an
+  authorized isolated environment, reproduce installation and required behavior from the lock.
+- **Routing owner:** Use `simplify` for proven removal. Use `realign` for dependency-boundary repair. Stop for
+  explicit authority when the correction needs an installation, license decision, credential, or
+  external write.
+- **Applicable principles:** [P048](../../_support/docs/principles/README.md#p048),
+  [P050](../../_support/docs/principles/README.md#p050),
+  [P055](../../_support/docs/principles/README.md#p055),
+  [P057](../../_support/docs/principles/README.md#p057),
+  [P061](../../_support/docs/principles/README.md#p061), and
+  [P062](../../_support/docs/principles/README.md#p062).
+- **Sources:** [GitHub guidance for review of AI-generated code](https://docs.github.com/en/copilot/tutorials/review-ai-generated-code)
+  and [We Have a Package for You!](https://www.usenix.org/conference/usenixsecurity25/presentation/spracklen).
+
+## Trust boundaries, authorization, and secrets
+
+- **Signal:** Code removes or bypasses authorization. It accepts untrusted data without boundary
+  validation. It fails open when security state is unknown. Untrusted input reaches an evaluation,
+  command, query, markup, or deserialization sink. A credential or sensitive value appears in code,
+  a fixture, a prompt, a log, or an artifact.
+- **Required evidence:** Trace the untrusted source to the protected operation or sink. Bind the
+  authorization policy, trust boundary, data classification, validation and encoding rules, failure
+  state, and credential owner. Do not print or copy a suspected secret.
+- **Impact:** The defect can disclose data, grant an unauthorized capability, execute injected input,
+  or expose a credential.
+- **Legitimate counterexample:** The value is a documented non-secret test token that cannot grant a
+  capability. A typed and validated value reaches a context-safe API. An authoritative boundary
+  performs complete mediation.
+- **Smallest safe correction:** Restore authorization at the authoritative boundary. Parse, validate,
+  constrain, and safely encode untrusted data. Use parameterized APIs. Remove a secret from source and
+  history only through an authorized security procedure. Rotate or revoke an exposed credential.
+- **Validation:** Add or run behavior tests for denied access, invalid input, failure state, and safe
+  encoding. Run repository-approved secret and security checks. Do not put secret material in the
+  validation receipt.
+- **Routing owner:** Use `realign` with a qualified security reviewer. Treat a possible live secret or a
+  material authorization bypass as a stop condition. Deleting a secret from one file is not complete
+  remediation because it does not revoke the credential or remove history.
+- **Applicable principles:** [P035](../../_support/docs/principles/README.md#p035),
+  [P048](../../_support/docs/principles/README.md#p048),
+  [P049](../../_support/docs/principles/README.md#p049),
+  [P050](../../_support/docs/principles/README.md#p050),
+  [P051](../../_support/docs/principles/README.md#p051),
+  [P053](../../_support/docs/principles/README.md#p053),
+  [P056](../../_support/docs/principles/README.md#p056), and
+  [P069](../../_support/docs/principles/README.md#p069).
+- **Sources:** [AISlop 0.16.0 security rules](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md#security)
+  and the [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html).
+
+## Performance changes without evidence
+
+- **Signal:** A change adds a cache, concurrency, batching, pooling, manual memory control, or a more
+  complex algorithm without a measured constraint. A claim uses only a complexity warning, intuition,
+  or a benchmark result that is not bound to the reviewed revision.
+- **Required evidence:** Identify the product constraint and representative workload. Bind the
+  baseline and candidate revisions, environment, benchmark command, samples, variance, resource
+  limits, and correctness checks. Separate latency, throughput, memory, and cost claims.
+- **Impact:** Speculative optimization can add state, races, invalidation defects, and maintenance
+  work without a useful result.
+- **Legitimate counterexample:** A current requirement or verified resource bound requires the design.
+  Evidence shows the constraint, and the repository already uses the selected mechanism.
+- **Smallest safe correction:** Remove speculative complexity when it has no current requirement.
+  Otherwise, measure first and make the smallest change that satisfies the measured constraint.
+- **Validation:** Reproduce the baseline and candidate measurements in the same controlled
+  environment. Run behavior, failure, concurrency, and resource-limit tests that the change affects.
+- **Routing owner:** Use `realign` for an evidenced structural correction. Use `simplify` to remove
+  speculative machinery. Use `retain` when evidence does not support a change.
+- **Applicable principles:** [P065](../../_support/docs/principles/README.md#p065),
+  [P072](../../_support/docs/principles/README.md#p072),
+  [P073](../../_support/docs/principles/README.md#p073), and
+  [P080](../../_support/docs/principles/README.md#p080).
+- **Sources:** [Athena evidence-integrity policy](../../_support/docs/policies/evidence-integrity.md) and
+  [Brendan Gregg's performance-analysis methodology](https://www.brendangregg.com/methodology.html).
+
+## Comments, documentation, and excessive churn
+
+- **Signal:** A comment only narrates mechanics, refers to an agent or implementation phase, or
+  repeats a symbol name. Documentation claims behavior that the product does not have. A change
+  includes unrelated formatting, renames, compatibility residue, TODO stubs, or broad rewrites.
+- **Required evidence:** Compare the prose with code, contracts, public behavior, history, generation
+  policy, and the requested scope. Identify the maintenance or review effect. Do not use comment
+  length or changed-line count alone.
+- **Impact:** Misleading prose can hide an invariant or false behavior claim. Unrelated churn can
+  conceal a defect, create conflicts, and make ownership history difficult to inspect.
+- **Legitimate counterexample:** A comment records rationale, a non-obvious invariant, a security
+  constraint, compatibility evidence, or a required generation notice. A mechanical rewrite is a
+  separately authorized migration with reproducible validation.
+- **Smallest safe correction:** Make code show its mechanics. Keep necessary rationale. Correct
+  behavior claims. Remove obsolete prose and unrelated residue only after consumer and history
+  evidence makes deletion safe.
+- **Validation:** Run documentation, link, example, formatting, and behavior checks that the changed
+  surface activates. Inspect the final diff for unrelated paths and stale identifiers.
+- **Routing owner:** Use `simplify` for safe deletion, consolidation, or churn removal. Use `realign` only
+  when prose or churn conceals an architecture, invariant, or contract defect. Otherwise, use
+  `retain`.
+- **Applicable principles:** [P010](../../_support/docs/principles/README.md#p010),
+  [P014](../../_support/docs/principles/README.md#p014),
+  [P066](../../_support/docs/principles/README.md#p066),
+  [P070](../../_support/docs/principles/README.md#p070),
+  [P086](../../_support/docs/principles/README.md#p086),
+  [P087](../../_support/docs/principles/README.md#p087),
+  [P088](../../_support/docs/principles/README.md#p088), and
+  [P090](../../_support/docs/principles/README.md#p090).
+- **Sources:** [AISlop 0.16.0 rules](https://github.com/scanaislop/aislop/blob/v0.16.0/docs/rules.md),
+  [SlopCodeBench](https://arxiv.org/abs/2603.24755), and a
+  [practitioner discussion](https://news.ycombinator.com/item?id=45535937).
+
+## Catalog boundary
+
+Do not create a finding because a repository contains mocks, comments, dependencies, asynchronous
+code, or optimization. Do not remove a security check as simplification. Do not add a dependency to
+repair an unsupported scanner diagnostic. Route an observed defect through the workflow that owns
+behavior repair. Route a safe subtraction through `simplify`.