Agent Engineering Rules v5.0.0

AER v5 succeeds v3.1.1 directly. V4 was an unreleased experiment and is skipped.

What changed

• A compact 45-line universal contract puts complete behavior, coherent design, exact contracts, engineering judgment, and evidence-backed completion first. Diff size is neutral; both symptom patches and speculative architecture are discouraged.
• Verification investment follows the feature's risk, lifespan and stability. Permanent tests are a separate decision, valid evidence is reused, and selected UI guidance explicitly covers draft preservation and keyboard focus after rendering.
• aer verify <contrast|slop|size> selects an optional diagnostic. It does not run project scripts or certify completion. Runtime modules ship once and are installed through the existing ownership checks.
• Provider-free validators cover the corpus, all 110 grievance owners, frozen historical records, complete instruction loads and the actual npm package. Dormant evaluation execution machinery is removed.

Install or upgrade

Requires Node.js 24 or newer.

npm install --global @aaarslan/aer@5.0.0

# New managed project: choose the host actually used by the repository.
aer init --host codex --dry-run
aer init --host codex

# Existing managed project after upgrading the CLI.
aer update --dry-run
aer update
aer doctor

Use --host claude for Claude Code or --host both when both are used. Preserve the existing ownership ledger and consumer instructions. V4 experimental hook/runtime installs are not a supported automatic migration source. Installation and migration explain collision and recovery behavior.

Validation and evidence limits

The full local release gate passed: 62 main tests, 6 research tests, 91 source files, 39 expanded load plans and an isolated installation of the 96-file package. Linux, Windows, research validation and CodeQL passed on the release PR and merged commit. PR #10 contains the reviewed change; release validation and CodeQL record the merged checks.

No general efficacy, token savings or verification-cost claim is made. In one known-task comparison, v5 and v3.1.1 tied at ten of ten exercised groups and the baseline passed eight. V3.1.1's reset check used a confirmation adapter; the native dialog remains unverified. The comparison record preserves those qualifications.

The attached package and SHA-256 checksum identify the validated release artifact. Full changelog.

Agent Engineering Rules v3.1.1

3.1.1 - 2026-09-01

Source corpus:

• Made each applicable UI action prove a named visible destination state in prompt vocabulary; acknowledgements alone no longer qualify. Required destinations must remain discoverable, keyboard/pointer reachable, and correctly activated at relevant narrow breakpoints, with document overflow assessed separately from intentional local scrolling.
• Required a clean applicable full-root rerun or explicit fingerprint disposition for residual slop findings. Remaining rendering sinks must be absent after removal, safely escaped by a named mechanism, bounded trusted static data, or disclosed as unresolved; unresolved sinks block clean claims.
• Tightened verification stopping and truthfulness: ordinary standard-profile greenfield UI work prefers one full-root slop scan and one contrast batch, unchanged help/check retries stop after usable evidence, component failures cannot be masked by later successes, and known residual defects remain disclosed.
• Required direct enumeration and validation of untracked authored output, a retained lockfile or repository exact-pin policy for introduced dependencies, and bounded terminating builds that produce their declared output rather than leave a development server running.
• Kept the universal contract and profiles unchanged. UI completion remains progressively disclosed and now reports composition/form factor, functional/responsive behavior, and engineering/accessibility/safety in three concise outcome lines without treating framework choice, file count, LOC, ARIA quantity, or validation volume as a verdict.

Claude distribution:

• Regenerated the feature and UI-styling skills plus the Web UI and verification references from the canonical routed source. The always-active Claude contract and profile remain unchanged.

Codex distribution:

• Regenerated the matching skills and on-demand references without expanding the managed AGENTS.md universal contract.

Tools, package, and validation:

• Made normal slop root scans exclude co-located managed agent-rules/ and .agents/ trees as well as generated, dependency, and vendor material while preserving explicit targeting; findings now carry stable fingerprints and results distinguish full-root from partial-selector scope.
• Gave each shipped utility one canonical documented invocation while retaining compatible focused forms and the contrast checker's existing pass/fail calculation and file guard's advisory behavior.
• Added deterministic regressions for prompt-state versus acknowledgement, a 390×844 sidebar transformation, managed/static/generated/partial slop scopes, stable sink fingerprints and dispositions, untracked authored files, masked command failures, valid and nonterminating builds, and lockfile/exact-pin dependency policy. Existing seeded contrast and slop defects remain covered.
• Bumped the public package, citation metadata, exact-version examples, and issue template to @aaarslan/aer 3.1.1.

Evaluation and migration:

• This patch responds to supplied independent post-3.1.0 replication evidence, which remained read-only. No OneShotBench evidence was changed or copied into the package, and the expensive full matrix was not rerun.
• The expected effects—fewer malformed invocations, self-scan findings, unchanged retries, and unsupported clean/completion claims without losing seeded-defect detection—are hypotheses grounded in that evaluation. This release makes no statistical or general efficacy claim.

Agent Engineering Rules v3.1.0

AER 3.1 turns observed agent failures into explicit, cross-platform engineering checks. This release is evidence-informed and deterministically validated; it does not claim statistically proven comparative efficacy.

Agent Engineering Rules v3.0.1

Install AER once from npm

npm install --global @aaarslan/aer

aer init --host claude --dry-run
aer init --host claude
aer doctor

Global installation is only a distribution convenience. AER-managed configuration, generated content, ownership state, and markers remain exclusively inside the selected repository. No global agent settings, consumer CI, hooks, services, daemons, telemetry, or install scripts are added.

CLI lifecycle

Upgrade the installed CLI:

npm install --global @aaarslan/aer@latest

Update an already managed repository using the installed CLI version:

aer update --dry-run
aer update

aer update does not upgrade the globally installed CLI.

Remove AER from a repository and remove the global CLI:

aer uninstall --dry-run
aer uninstall

npm uninstall --global @aaarslan/aer

For an exact reproducible one-shot execution:

npm exec --yes --package=@aaarslan/aer@3.0.1 -- aer init --host claude --dry-run

What changed

• Published the zero-dependency aer CLI as the public npm package @aaarslan/aer@3.0.1.
• Preserved the Node.js >=24 requirement and project-local ownership model.
• Added deterministic version/help behavior and complete provider-free release validation.
• Added isolated packed-install coverage on Linux and Windows.
• Verified the public npm package through a fresh isolated Windows installation and clean-project lifecycle smoke test.
• Shipped 95 audited files containing the CLI, required Claude and Codex distributions, license, and user documentation.

See the v3.0.1 changelog for complete details.

Agent Engineering Rules v3.0.0

AER v3 is a greenfield release of compact, project-local engineering rules for Claude Code and OpenAI Codex.

Highlights

• One model-neutral 25-directive contract with bounded profiles and on-demand skills.
• A zero-dependency aer CLI with ownership-safe init, update, doctor, and uninstall flows.
• Native Claude Code and Codex distributions generated from one canonical source.
• Hardened path, symlink, collision, recovery, and concurrent-change validation.
• Provider-free Linux and Windows CI plus CodeQL, Dependabot, secret scanning, and protected releases.
• New security policy, contribution guide, issue forms, pull-request template, citation metadata, and community discussions.

Quick start

Requirements: Node.js 24 or newer and a Git repository.

npm exec --yes --package=github:aaarslan/agent-engineering-rules#v3.0.0 -- \
  aer init --host claude --target . --dry-run

After reviewing the preview, remove --dry-run. Use --host codex or --host both when appropriate.

See the full changelog and installation guide.

Security reports should use private vulnerability reporting, not public issues.