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.