Fail Closed Code Hygiene

# Fail-Closed Code Hygiene

Use this maintainer-only skill when a pass is explicitly about removing AI
slop, fake modularization, duplicate helper churn, mirror drift, oversized-file
pressure, or other structural debt in shipped Odylith code.
Treat AI slop as a regression.
Apply that bar to any codebase or project surface in this lane: services,
libraries, apps, CLIs, infra glue, scripts, docs, prompts, hooks, templates,
config, and generated assets all count.
Structural cleanup is not permission to drift behavior, UX, or UI. Preserve
semantics deliberately and prove the touched contract on the real toolchain or
surface that owns it.
No transitional states. Do not replace one slop class with another.

## Read First
- Read the nearest `AGENTS.md`.
- Read `../../agents-guidelines/ANTI_SLOP_AND_DECOMPOSITION.md`.
- Read `../agents-guidelines/CODING_STANDARDS.md`.

## Required Workflow
- Inventory the bounded slop in the touched slice before editing:
  - remaining `def _host()` or `host = _host()` shims
  - duplicate `_mapping`, `_normalize_*`, `_delta`, `_parts`, or similar
    helper clones
  - transitional alias walls that still hide the owner after a fake seam was removed
  - host-mirror files that should share a helper or formatter
  - phase-mixed giant render, payload, router, or score functions
  - touched hand-maintained source files already above the repo size limits
  - install-managed mirror surfaces that will need sync
- Record the before-state in concrete terms before you edit:
  line counts for any touched `1200+` / `2000+` files, the exact helper or
  mirror clones you plan to remove, and the proof surface you will rerun.
- Record the lane and host reach as well: which shared guidance, install-
  generated guidance, Codex assets, Claude assets, shared skills, and shipped
  mirrors must stay aligned if the anti-slop rule changes.
- Record project-surface reach too: source files, hooks, prompts, templates,
  config, docs, generators, and installed assets that may be carrying the
  same slop class under different file extensions.
- Pick a real owner. Move shared coercion, normalization, or rendering logic
  into a stable owner instead of adding another wrapper layer.
- Do not treat a shared helper or kernel as a cleanup ornament. If it lands,
  adopt it in the touched slice or leave a bounded follow-up tied to the same
  slop class.
- Do not hide the old owner behind compatibility wrappers, lazy proxies,
  facade accessors, or mirror-only indirection after a nominal extraction.
- Partial shared-kernel adoption is still incomplete. If a shared helper or
  kernel lands, the touched callers must adopt it or the pass is incomplete.
- When you touch a shimmed extract, remove the shim in the same pass.
- When you touch a giant function, extract at least one real phase owner or
  data-model seam in the same pass unless the change is purely a
  safety-critical repair.
- When you create a shared owner, update the touched duplicates onto it before
  closeout.
- Do not call the pass complete just because the first smell disappeared. If
  the replacement smell still exists in the touched slice, the pass is
  incomplete.
- When you touch a red-zone source file, leave it with a smaller or cleaner
  owned boundary than you found. Do not use a hygiene pass to sneak in net new
  unrelated growth.
- When guidance, hooks, skills, or bundle-managed assets change, update the
  live source and every shipped mirror in the same change.
- For maintainer product-surface changes that can affect already-installed
  consumer repos, run `odylith release migration-gate --repo-root .
  --target-version <version>` and satisfy the exact emitted
  `migration-observer:<version>:<surface>:<fingerprint>` Radar marker before
  release closeout.
- Keep that migration-observer rule maintainer-only. Do not mirror it into
  consumer-safe shared skills, shared agent guidelines, or bundled install
  assets.
- Add inline documentation only for invariants, failure modes, boundary
  assumptions, or non-obvious state transitions.
- Add or update enforcement tests that pin the cleaned-up class of slop.

## Hard Bans
- `def _host()` plus a wall of rebound private host symbols is banned.
- A local alias wall that only renames a dense helper cluster without moving
  the owner is banned.
- Do not duplicate generic coercion helpers such as `_mapping`,
  `_json_dict`, `_normalize_*`, `_delta`, or `_parts` across files when one
  shared owner is appropriate.
- Do not hide the same slop class in Codex-only or Claude-only project assets,
  hooks, prompt builders, command shims, config templates, or generated
  guidance.
- In dev-maintainer lane, do not encode templatized conversations, canned
  narration, or patterned voice rails in maintainer-owned Odylith product
  surfaces. Prompts, hooks, renderers, tests, fixtures, skills, docs, and
  governance generators must preserve live narration assembled from current
  evidence. Tests may pin labels, schemas, evidence use, and anti-mechanical
  constraints, but must not force one canned sentence shape or reusable
  conversation script.
- Do not leave giant renderers, payload builders, or routers phase-mixed when
  the pass can split them into data prep, view model, and template/render
  stages, or gather, score, and decide stages.
- New or materially rewritten runtime Python modules must carry a truthful
  module docstring.
- Every anti-slop cleanup must add or update enforcement tests.

## Fail-Closed Exit Criteria
- No touched file may still contain `def _host()` or `host = _host()`.
- No touched file may keep an avoidable generic helper clone once the shared
  owner exists.
- No touched pass may leave a shared helper or kernel as an ornament while the
  touched callers stay on local forks without a bounded follow-up.
- No touched host-mirror pair may still keep avoidable shared control flow in
  both files once a real shared owner exists.
- No touched giant function may leave with the same phase-mixed ownership it
  had on entry when the pass is explicitly about structural debt.
- No touched file may replace a removed shim with an alias wall that still
  hides the real owner.
- Any touched red-zone file must exit with a clearer owned seam than it had on
  entry; if not, the pass is incomplete.
- Do not stop on "improved" when the same bounded slop class is still present
  in the touched slice. Fail closed on unresolved slop in the touched slice.
- Do not claim non-regression without proof.

## Required Proof
- Run focused regression tests for the touched slice.
- For shared hot paths, user-visible flows, or high-risk structural moves,
  land characterization or contract-focused tests before or alongside the
  refactor instead of relying on post hoc confidence.
- Run `tests/unit/runtime` when the change touches shared runtime hot paths.
- Run `tests/unit/install` when the change touches install, upgrade, repair,
  launchers, hooks, skills, or install-managed mirrors.
- When the anti-slop rule itself changes, prove the shared guidance, host
  contracts, install-generated guidance, shared skills, and shipped mirrors in
  the same pass.
- When the user asks for repo-wide or lane-wide anti-slop hardening, update
  guidance, skills, install-generated guidance, host contracts, mirrors, and
  enforcement tests together; prose-only hardening is incomplete.
- Guidance-only hardening without updated tests, validators, or mirror-content
  checks is incomplete.
- If the pass claims repo-wide or lane-wide cleanup, rerun the requested
  repo-wide structural scan or equivalent inventory before closeout.
- Repo-wide or lane-wide anti-slop claims require two proof layers: fresh
  behavior proof for the touched slice and a fresh structural inventory for
  the claimed scope. One does not substitute for the other.
- Run the headless browser matrix when the change touches browser-proved UI or
  shell surfaces.
- When browser proof applies, cover the real rendered states that own the
  contract: normal, empty/fallback, and degraded or error states when they
  exist.