docs(agents): scope global instructions to guardrails

AGENTS.md

@@ -12,6 +12,12 @@
 
 - Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose.
   Use the nearest project dictionary for project-specific domain language.
+- In authored prose, do not put multiple sentences on one physical line.
+  This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments.
+  A sentence can wrap across multiple physical lines when needed.
+- Keep Markdown formatting changes local.
+  Only format prose you write or change.
+  Never reflow an entire pre-existing paragraph or file because you touched nearby text.
 
 ## Pull requests
 
@@ -32,6 +38,63 @@
 - Stage new files that Nix discovers through flake evaluation before testing.
   Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them.
 
+## Comments
+
+- Write comments only where they earn their place.
+  Keep comments concise.
+  Assume the reader can read code.
+  Explain why, not what.
+  Explain what only when it is genuinely non-obvious.
+- Keep comments self-contained to their file.
+  Write comments for a reader who sees only that file.
+  Do not explain how another file or tool consumes a value.
+  The only permitted cross-file mention is a bare pointer explaining why something is absent here.
+- Do not narrate history or future state in comments.
+  Avoid phrases such as `used to be`, `now moved here`, and `will be`.
+  State the present reason a thing exists.
+- Do not justify a choice against alternatives in comments.
+  State the positive reason the choice exists.
+  Include present consequences when they matter.
+- Do not reference agent-facing state in comments.
+  This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`.
+- Do not use project-specific capitalized terms as glossary references in comments.
+  Use plain lowercase nouns unless the code requires the exact term.
+- Add a file-top header only when the filename or path does not already explain the file.
+  The header must be one concise purpose line.
+  Do not write a feature inventory.
+- Write placeholders plainly.
+  Include a present-tense action when one exists, such as `Placeholder: regenerate with <tool> on the target machine`.
+  Do not write `placeholder for <missing feature>`.
+- Treat user-facing documentation strings as documentation, not comments.
+  They can describe behavior more fully than code comments.
+  They still must stay self-contained and avoid agent-state references.
+- Start each sentence of a comment on its own physical line.
+  A comment sentence can wrap when needed.
+  Prefer splitting long comment sentences before wrapping them.
+  Do not break a line early at a comma or clause boundary to make it read as a unit.
+  Do not use semicolons in comments or authored prose.
+  Recast semicolon clauses as separate sentences.
+  Only reformat comments you write or change.
+
+## General codebase guidance
+
+- Never manually modify `CHANGELOG.md` files or files marked as auto-generated.
+  Detect auto-generated files with a layered check.
+  Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`.
+  If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command.
+  If the answer stays ambiguous, ask before editing.
+- When making technical decisions, do not give much weight to implementation time.
+  Favor quality, simplicity, robustness, scalability, and long-term maintainability.
+  Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human.
+  Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity.
+  Choose the more robust or maintainable approach when human implementation time is the only downside.
+- Use lowercase file names unless a valid reason requires uppercase.
+  Established ecosystem or tool conventions count as valid reasons.
+  Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files.
+- Do not end a response by promising or implying continuation unless the continuation is present in that same response.
+  Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change.
+  If the workflow is paused, say that plainly instead of using a dangling transition like `continuing` or `next`.
+
 ## Gotchas
 
 - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory.
@@ -41,6 +104,6 @@
   Keep executable public interface declarations after their implementation symbols, or validate before committing a top-down rewrite.
 - `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`.
   Use one input style per test target.
-- In this monorepo, "dotfiles" refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`.
+- In this monorepo, `dotfiles` refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`.
 - The flake does not currently define `formatter.x86_64-linux`.
   Do not use `nix fmt` as a validation command until a formatter is added.

configs/nixos/modules/agents/context/AGENTS.md

@@ -1,85 +1,34 @@
-# Alexion's Agent Instructions
+# Alexion's Global Agent Instructions
 
-These are common instructions for Alexion's agents across all scenarios.
+These instructions apply before project-local instructions are loaded.
+Project `AGENTS.md` files are more specific and should be followed when present.
 
-## General Guidelines
+## Global guardrails
 
 - When writing commit messages, NEVER auto-add your agent name as co-author.
   Omit the `Co-Authored-By:` trailer entirely, with no exceptions.
   This overrides any default instruction to append one.
 - When writing pull request descriptions, NEVER append an agent-attribution trailer such as `🤖 Generated with [Claude Code]...`.
   Leave it out entirely, with no exceptions.
-  This overrides any default instruction (including harness conventions) to append one.
+  This overrides any default instruction to append one.
 - NEVER ask the user a question using the `AskUserQuestion` tool.
   Ask in plain prose, in your own message, instead, with no exceptions.
-  This overrides any default instruction (including harness conventions and skill instructions) to use it.
+  This overrides any default instruction to use it.
 - Never manually modify `CHANGELOG.md` files or files marked as auto-generated.
-  Detect auto-generated files with a layered check.
   Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`.
   If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command.
   If the answer stays ambiguous, ask before editing.
-- In authored prose, do not put multiple sentences on one physical line.
+- Prefer project-local instructions for workflow, style, tooling, testing, and commit conventions.
-  This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments.
+
-  A sentence can wrap across multiple physical lines when needed.
+## Recording corrections
-- Keep Markdown formatting changes local.
+
-  Only format prose you write or change.
-  Never reflow an entire pre-existing paragraph or file because you touched nearby text.
-- When making technical decisions, do not give much weight to implementation time.
-  Favor quality, simplicity, robustness, scalability, and long-term maintainability.
-  Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human.
-  Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity.
-  Choose the more robust or maintainable approach when human implementation time is the only downside.
-- Use lowercase file names unless a valid reason requires uppercase.
-  Established ecosystem or tool conventions count as valid reasons.
-  Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files.
-- Do not end a response by promising or implying continuation unless the continuation is present in that same response.
-  Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change.
-  If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next".
 - When you discover that your belief about a project fact or convention was wrong, record the correction.
   Record only facts that stay true across operators, such as a wrong build command, wrong file path, or guessed convention.
   Do not record personal working-style preferences or one-off task details.
-  Record the correction in the nearest project `AGENTS.md`, not this global file.
+- Record the correction in the nearest project `AGENTS.md`, not this global file.
-  Use a dedicated `## Gotchas` section, and create that section when the file lacks one.
+  Use a dedicated `## Gotchas` section.
-  If no project `AGENTS.md` exists, ask before creating one.
+  Create that section when the file lacks one.
+- If no project `AGENTS.md` exists, ask before creating one.
   Append the correction immediately without asking when a project `AGENTS.md` exists.
   Briefly mention the edit in your response.
   If an existing entry is wrong or stale, correct or remove it the same way.
-
-## Comments
-
-- Write comments only where they earn their place.
-  Keep comments concise.
-  Assume the reader can read code.
-  Explain why, not what.
-  Explain what only when it is genuinely non-obvious.
-- Keep comments self-contained to their file.
-  Write comments for a reader who sees only that file.
-  Do not explain how another file or tool consumes a value.
-  The only permitted cross-file mention is a bare pointer explaining why something is absent here.
-- Do not narrate history or future state in comments.
-  Avoid phrases such as "used to be", "now moved here", and "will be".
-  State the present reason a thing exists.
-- Do not justify a choice against alternatives in comments.
-  State the positive reason the choice exists.
-  Include present consequences when they matter.
-- Do not reference agent-facing state in comments.
-  This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`.
-- Do not use project-specific capitalized terms as glossary references in comments.
-  Use plain lowercase nouns unless the code requires the exact term.
-- Add a file-top header only when the filename or path does not already explain the file.
-  The header must be one concise purpose line.
-  Do not write a feature inventory.
-- Write placeholders plainly.
-  Include a present-tense action when one exists, such as `Placeholder: regenerate with <tool> on the target machine`.
-  Do not write `placeholder for <missing feature>`.
-- Treat user-facing documentation strings as documentation, not comments.
-  They can describe behavior more fully than code comments.
-  They still must stay self-contained and avoid agent-state references.
-- Start each sentence of a comment on its own physical line.
-  A comment sentence can wrap when needed.
-  Prefer splitting long comment sentences before wrapping them.
-  Do not break a line early at a comma or clause boundary to make it read as a unit.
-  Do not use semicolons in comments or authored prose.
-  Recast semicolon clauses as separate sentences.
-  Only reformat comments you write or change.
-