Ansible/scripts/docs/AGENTS.md

# AIM authoritative development guidelines

**Baseline: 3.3.0rc8.** This is the current Core guide. Operator instructions take
precedence over earlier project documentation. Keep the built-in terminal in AIM.

## Product and release ownership

Core owns domain/execution truth, storage, reusable services and both first-party
interfaces. Dependencies point interface -> services/domain/runtime; services must
not import `aim.ui` or any add-on. Add-ons consume only `aim.services.v1` or `aimctl`.
No Core change may require inspecting or editing an independent add-on's codebase.

Release complete source ZIPs with SHA-256 sidecars and the operational deployer. No
Git/patch dependency, `.patch` file, release manifest, bundled test/validator machinery,
cache, inventory, Vault, private key, environment, downloaded package or collection.
Do not mutate a published candidate. Every source change updates the product version
and CHANGELOG. Service/wire/event 1.0 evolves additively; breaking changes require a
separately versioned contract. Product and API versions are not interchangeable.

## Layout and preservation

`/etc/ansible/scripts` contains source, pyproject, global `aim.yml`, docs and the WinRM
helper. `playbooks` contains the catalog, schemas and report filter plugins. `roles`
contains execution roles. Customer `.aim.yml` remains in its customer directory.

Deployment preserves operator config, inventory/Vault/keys, add-ons, environments and
customer assets. Preview first; quiesce writers/runners; maintain source/launcher
recovery. Retire only explicitly named old Core documents, never arbitrary Markdown.
Do not reset LDAP groups, permissions or ownership recursively. Stable lock inodes and
metadata-preserving atomic replacement apply. Source rollback cannot undo remote work.

## Execution and credentials

Canonical native runtime: ansible-core 2.19.11. AIM and add-on Python environments may
be separate; do not install/upgrade Ansible during discovery or deployment. New service
profiles stay opt-in. Require the actual execution UID/groups, owner-only private keys,
usable collections and sandbox staging. Check both process/config HOME and passwd/NSS
home paths where local delegation expands `~account`. Never override remote_tmp globally,
switch UIDs or edit service units to hide a staging/access failure.

Credentials use bounded one-run providers/private descriptors/sockets, never request
JSON, argv, environment, output, examples or persisted plans. Supplied passwords remain
native defaults, not forced inventory overrides. Existing Vault unlock retries are
pre-launch only. Preserve selection on typos and Ctrl+C cancellation; never replay a
launched editor/playbook automatically. Source and prepared revisions are change
detectors, not authorization tokens or isolation from uncooperative shell edits.

## Structured purposeful results

Use `ansible.builtin.set_stats` with `data.aim_output`, `protocol: aim_output_v1`, a static
schema ID, `per_host` matching the declaration and `aggregate: false`. Exactly one
publication per host (or one global publication) per execution. Result normalization
belongs in runbook roles/filter plugins, not hard-coded playbook branches in Core.

Declare result shape/scope/required/sensitivity in the catalog. Define bounded types in
`playbooks/schemas/`. The generic validator owns type/field/size/lifecycle enforcement;
new schemas require no Core dispatch additions. Revalidate at the callback and public
boundary. Preserve no_log provenance: final custom stats alone are not authorization
to expose data. Unknown custom stats/debug/module results remain private.

Operation reports, target outcomes and progress are separate. A required missing or
invalid report can fail result validation after native exit 0; preserve exit_code and
native target stats, and never replay. Interrupted output is indeterminate. On native
failure retain available final reports without replacing the original failure.

Declare operational field meanings precisely: bytes, observed versions, nullable
unknowns, bounded fixed error codes. Never guess an installed version from a staged
filename, imply a start return means a service stayed running, or call check-mode
predictions completed changes. Patch reports must not silently truncate update lists.
Checkmk config is parsed and redacted before publication; the filename alone does
not make passphrases/MRPE command credentials safe. Raw configuration diffs stay private.

Windows patching is operator-wave controlled: let the supported `win_updates` module process the currently approved update wave with module reboot disabled, then treat any resulting reboot as the boundary. Post-reboot rediscovery/continuation must be an explicit catalog option defaulting false; never turn a normal patch run into an implicit "keep patching until current" workflow. Preserve bounded per-update HRESULT reporting and never equate `0x80240016` alone with a proven pending reboot.

## Existing compatibility and Checkmk boundaries

Keep HTTPS WinRM 5986 and guarded legacy certificate fallback. Preserve standalone
local-account token handling. Do not add legacy-only external bootstrap dependencies.
Windows bootstrap compatibility is separate from collection/module requirements;
never claim every new playbook was tested on Server 2012 R2/PowerShell 4.

AIM owns catalogued check filenames, not whole directories. Unknown files stay.
Windows configuration management owns only `plugins:`; preserve `local`, `mrpe`,
`global`, unknown sections and comments. Keep the first-line notice plus section
ownership marker. Unmanaged sections are not empty generated mappings. Avoid unmatched
quote characters even in inline free-form shell comments. No unrelated firewall policy
changes or cleanup expansions in a reporting release.

AIM-managed persistent Windows Checkmk files use the shared `checkmk_windows_acl` role: enable parent inheritance per file and guarantee well-known SID access for SYSTEM/local Administrators (FullControl) and both application-package principals (ReadAndExecute). Do not add customer-specific administrator/user ACEs, recurse over whole Checkmk directories, or rewrite unknown/operator-file ACLs.

## Verification and documentation

Tests live outside the shipped release. Parse/compile sources, validate YAML/Jinja,
exercise credential/process/output boundaries and installer rollback. Use native
Ansible/collections when available and label simulations distinctly. Record failures,
missing dependencies and platform acceptance honestly in `scripts/docs/VALIDATION.md`.
Keep exactly one current API, release notes, handoff, sanity checklist and validation
record; the documentation index names the authority for each topic. Historical
CHANGELOG entries are retained, not represented as present-day capability guarantees.