---
name: agent-native-hardening
description: "Architecture hardening: ownership, boundaries, contracts, state safety, duplication, execution/import topology, traversability, feedback loops, test fit, change decomposition. Use for structural reviews, scorecards, plans, refactors, or startup/import-path analysis; not ordinary fixes or unmeasured micro-optimization."
---

# Agent-Native Hardening

## Reference map

Read only the references relevant to the task:

- `references/scoring-rubric.md` before assigning scores or producing a formal scorecard.
- `references/work-lanes.md` before splitting broad discovery or implementation across lanes, agents, branches, or worktrees.
- `references/dependency-safety.md` when dependency changes, installers, lockfiles, toolchains, package scripts, or supply-chain recommendations are in scope.
- `references/execution-topology.md` when call stacks, dispatch, middleware, callbacks, async continuations, imports, initialization, startup, bundle cost, or runtime-path navigability are in scope.
- `references/js-ts.md`, `references/python.md`, `references/rust.md`, or `references/go.md` for languages present in the target repo.

If no bundled language reference fits, use the general workflow and verify ecosystem-specific advice against the repo and current official documentation. Repo evidence and host constraints outrank generic guidance.

## Operating principles

1. **Evidence before prescription.** Inspect the real ownership, change paths, tooling, and failure modes before recommending a target architecture.
2. **Clear ownership over arbitrary size limits.** A large file is not automatically a godfile; the problem is unrelated responsibilities, hidden coupling, or repeated central-path edits.
3. **Feature ownership over catch-alls.** Prefer modules with clear domain or platform owners. Do not replace one godfile with `utils`, `helpers`, `common`, or excessive micro-files.
4. **Explicit contracts at boundaries.** Validate external data once, preserve named domain shapes internally, model state transitions, and derive contracts from a source of truth where practical.
5. **Stable reuse over premature DRY.** Extract duplication when the behavior is genuinely shared and has a clear owner; tolerate local duplication when semantics are still diverging.
6. **The shortest correct change path should be obvious.** Entry points, extension points, state owners, and validation commands should be discoverable without rereading the whole system.
7. **Every execution hop earns its place.** Preserve calls that own decisions, contracts, effects, lifecycle, resilience, or observability; collapse pass-through indirection and prefer control transfers an agent can resolve from code.
8. **Performance claims require runtime evidence.** Distinguish semantic navigability from measured call, import, initialization, startup, or bundle cost. Optimize the relevant hot or cold path for the repo's actual runtime and toolchain.
9. **Tests follow risk.** Match the repo's established testing intent and protect consequential behavior; do not manufacture coverage, fixtures, mocks, snapshots, or end-to-end scaffolding by default.
10. **Failures stay visible.** Fix root causes instead of weakening checks, suppressing diagnostics, swallowing errors, or adding silent fallback behavior.

## Workflow

### 1. Establish scope and mode

- Determine whether the user wants a review, scorecard, plan, implementation, or combination.
- Respect the requested scope. Do not turn a focused module cleanup into a repo-wide program.
- For edits, inspect git state and repo instructions before changing files. A dirty tree does not block read-only review, but report it and do not overwrite unrelated work.
- Identify active format, lint/static-analysis, type/contract, test, build, and aggregate check commands.

### 2. Map the relevant system

- Trace entry points, the real synchronous call stack, dynamic dispatch, async continuations, feature owners, state mutation, IO boundaries, contracts, and affected checks. Do not infer runtime flow from folders alone.
- When startup, imports, or runtime efficiency matter, map the relevant import/initialization path and collect representative measurements before attributing cost.
- Inspect hotspots for mixed concerns, central-handler growth, no-value frames, generic dispatch, callback or middleware tunnels, hidden side effects, positional data, duplicated contracts, manual lifecycle resets, and broad cross-feature coupling.
- Distinguish generated/framework-required structure from code humans are expected to maintain.
- For broad or unfamiliar repos, use focused read-only discovery lanes when they reduce rereading. Direct inspection is sufficient when the scope fits one coherent context.

### 3. Form evidence-backed findings

- Cite concrete files, symbols, flows, or commands.
- Explain the change risk, not merely the aesthetic preference.
- Separate observed defects from inference and optional modernization.
- Rank only material findings. Mention healthy boundaries where they affect the recommendation.
- Score only when the user requested scoring or a broad audit would clearly benefit from it; then read `references/scoring-rubric.md` first.

### 4. Choose the smallest coherent intervention

- Prefer one owned extraction or contract boundary over a speculative architecture rewrite.
- Split by feature ownership first, then by concern where the feature needs it.
- Keep central paths as small, statically enumerable routers, registries, or composition roots; move feature behavior behind explicit boundaries without hiding the selected implementation.
- Collapse pass-through wrappers and single-use microfunctions only when they own no decision, translation, contract, effect, lifecycle, resilience, or observability boundary.
- Model impossible or ambiguous states with variants, enums, validators, domain values, or named objects appropriate to the language.
- For broad multi-area work, read `references/work-lanes.md` and create only as many lanes as have independent objectives and validation.

### 5. Implement without laundering failures

- Preserve behavior unless behavior change is explicitly in scope.
- Keep edits owned and traversable; avoid parallel abstractions that leave the old path alive.
- Run relevant checks during the work and the repo's appropriate aggregate check at the end.
- Do not make checks pass through broad ignores, weaker strictness, unsafe casts, blanket suppressions, skipped files, or unrelated test deletion.
- Do not upgrade dependencies, runtimes, compilers, package managers, or lint policy unless the user accepted that work.

### 6. Stabilize and report

- Verify the final ownership and call path, not only compilation.
- If parallel lanes or branches were used, integrate centrally and resolve overlap before final checks.
- Report what changed, why the new boundary is safer, validation run, and remaining material risks.
- For review-only work, lead with severity-ordered findings and stop without implementation.

## Architecture and contract checks

Evaluate these where relevant:

- root objects route and compose rather than own feature-local state
- feature additions primarily touch feature-owned modules, with small registration changes in central paths
- important execution paths use recognisable feature terminology and each hop has an explainable role
- dynamic dispatch, decorators, middleware, callbacks, generated bindings, and async hand-offs remain inspectable in both directions
- imports and module initialization avoid hidden IO, surprising global mutation, cycles, or eager cold-path work where the runtime makes those costs material
- orchestration, domain rules, IO, rendering, and mutation are separated where mixing them raises change risk
- async/background work has a clear owner, result/message shape, cancellation or shutdown path, and state mutation boundary
- render/view functions avoid hidden IO or mutation where the framework permits
- named objects survive until serialization/render boundaries instead of becoming magic indexes, tuples, parallel arrays, or string lists
- reset/cleanup behavior is owned rather than scattered through null, empty, or sentinel assignments
- shared code has a stable owner and does not become a dumping ground
- comments explain invariants, ordering, side effects, or non-obvious ownership rather than restating code

## Scope, documentation, and modernization

- Add documentation only when it reduces future discovery cost. Prefer accurate entry-point maps and local invariant comments over broad prose.
- Do not rewrite user-facing README material unless it is part of the requested hardening scope.
- Treat toolchain, dependency, lint-policy, lazy-loading, bundling, and runtime changes as opt-in modernization. Explain evidence, benefit, migration cost, and risk before implementation.
- Do not use “agent-friendly” to justify product scope expansion, framework churn, new infrastructure, or unfamiliar dependencies.
- Read `references/dependency-safety.md` before dependency or installer changes.

## Output by task

- **Focused review:** material findings with evidence, impact, and a specific recommendation.
- **Scorecard:** severity-ordered findings, rubric scores with evidence, and the highest-leverage next steps.
- **Plan:** ordered interventions, ownership boundaries, affected files, dependencies between steps, and validation.
- **Implementation:** concise change summary, new ownership/contract shape, checks run, and remaining risks.

Do not emit every format for every task. Match the deliverable to what the user asked for.
