# AGENTS.md

## Purpose
This file defines agent behavior, contribution standards, and validation rules for this repository.

## Scope
- Applies to the entire repository unless a deeper `AGENTS.md` overrides it.

## Repository Baseline
- Source of truth is `scripts/build_tracker_workbook.py`.
- `nessus_remediation_tracker.xlsx` is a generated artifact and must be regenerated when workbook logic changes.
- Keep workbook logic compatible with both Excel and Google Sheets formulas.
- Keep dependency documentation in `README.md` accurate when Python module usage changes.
- Policy: any `Template` cell auto-populated from `Key` lookups must resolve to blank when the source `Remediations` value is missing/empty.

## File Standards
- Use Unix `LF` line endings for all text files.
- Preserve existing style and formatting conventions.
- Keep config examples free of real secrets.
- Prefer concise docs that describe operator workflow.

## Change Boundaries
- Keep edits minimal and directly tied to the request.
- Do not modify unrelated files or behavior.
- Preserve backward compatibility unless explicitly approved.

## Git Workflow
- Default flow: `git status` -> `git add` -> `git commit` -> `git push`.
- Use non-interactive git commands.
- Commit messages should be imperative and specific (example: `Use openpyxl to generate tracker workbook`).
- If `git push` fails, retry one additional time before escalating.
- Do not amend commits unless explicitly requested.

## Changelog Policy
- Keep a top-level `CHANGELOG.md`.
- Update changelog for any user-visible behavior change, generated workbook structure change, or workflow change.
- New entries go at the top with date (`YYYY-MM-DD`) and short bullets.

## Validation
- Run checks for changed areas.
- Minimum validation for workbook changes:
  - `python3 scripts/build_tracker_workbook.py`
  - `python3 -m py_compile scripts/build_tracker_workbook.py`
  - `unzip -t nessus_remediation_tracker.xlsx`
- If a check cannot run, state exactly why in the final summary.
- Report exact validation commands run in the final summary.

## Safety
- Do not run destructive commands (for example `rm -rf` or `git reset --hard`) unless explicitly requested.
- Ask before high-impact or irreversible operations.
- Never overwrite unrelated user changes.

## Documentation
- Update `README.md` when behavior, configuration, or workflows change.
- Ensure docs match current script dependencies and usage.
- If dependency requirements change, update both installation commands (`apt` and `pip`) in `README.md`.

## Output Expectations
- Final summaries should include:
  - files changed
  - behavior impact
  - validation performed
  - risks or follow-up actions