Backport: Add agentic coding guidance and docs

.gitignore

@@ -55,3 +55,13 @@ releasenotes/build
 # Files created by alembic
 /nova.db
 /nova_api.db
+
+# agentic tools and files
+.tmp/
+.pi/
+.cursor/
+.cursorrules
+.claude/
+.vscode/
+.codex/
+CLAUDE.md

AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md — agent routing index
+
+Agents: explore the repo directly; this file is a routing index, not a contributor guide.
+
+## Workflow
+
+**Session memory:** Write plans, notes, and ephemeral files to `.tmp/`
+(gitignored) rather than the system temporary directory.
+
+**For non-trivial planning**, inspect deps and tooling:
+`pyproject.toml` · `tox.ini` · `.pre-commit-config.yaml` ·
+`requirements.txt` · `test-requirements.txt`
+
+**Tests**: Use `tox` or `stestr`; never use `pytest`.
+  Invoke them directly, for example `tox -e pep8`.
+  Assume project tools are installed and available on `$PATH`.
+
+**Routing:**
+- Repo layout: [doc/source/contributor/repo-overview.rst](doc/source/contributor/repo-overview.rst)
+- Style, hacking, checks: [HACKING.rst](HACKING.rst)
+- RPC: [rpc.rst](doc/source/reference/rpc.rst)
+- Conductor: [conductor.rst](doc/source/reference/conductor.rst)
+- REST API: [api.rst](doc/source/contributor/api.rst)
+- Microversions: [microversions.rst](doc/source/contributor/microversions.rst) / [api-microversion-history.rst](doc/source/reference/api-microversion-history.rst)
+- Concurrency/threading: [threading.rst](doc/source/reference/threading.rst) / [concurrency.rst](doc/source/admin/concurrency.rst)
+- Test conventions, fixtures: [HACKING.rst](HACKING.rst) / [testing.rst](doc/source/contributor/testing.rst)
+- Dependencies and packaging: [dependencies.rst](doc/source/contributor/dependencies.rst)
+- Documentation: [documentation.rst](doc/source/contributor/documentation.rst)
+- Commit messages: [commit-messages.rst](doc/source/contributor/commit-messages.rst)
+- Agentic coding conventions: [agentic-coding.rst](doc/source/contributor/agentic-coding.rst)
+
+## Guardrails
+
+- **Tools:** Do not install missing tools with a package manager or `pip`
+- **Concurrency**: Do not introduce asyncio or new eventlet usage. Review the
+  threading and concurrency docs when changing concurrent code.
+- **Review**: Nova uses Gerrit, not GitHub PRs. Series are always unsquashed;
+  each commit must be independently testable and correct.
+- **Git**: Read-only operations (`git log`, `git diff`, `git status`) are fine.
+  Do not run mutating operations (`add`, `commit`, `reset`, `checkout`, `push`,
+  `stash`, `merge`, `rebase`, etc.) unless explicitly instructed to do so.

doc/source/contributor/agentic-coding.rst

@@ -0,0 +1,126 @@
+.. _agentic-coding:
+
+==============
+Agentic Coding
+==============
+
+This document covers Nova's conventions for AI-assisted development: how
+shared project guidance is structured, what belongs in ``AGENTS.md``, and how
+contributors should configure local tooling.
+
+Philosophy
+==========
+
+Nova's approach to agentic coding is minimal scaffolding and native
+discovery: if a convention must be followed it is documented in human-readable
+prose that agents can find via normal file exploration. Agent context files
+are kept short so they route rather than encode knowledge.
+
+Principles
+==========
+
+Tool-neutral documentation
+--------------------------
+
+Nova contributor documentation is written for contributors first. Mention
+specific AI coding tools only when documenting tool-specific behavior or local
+configuration examples. Prefer general wording such as "contributors" and
+"readers" when the guidance applies to everyone.
+
+Canonical human-readable docs
+-----------------------------
+
+Project rules and conventions belong in human-readable documentation,
+``HACKING.rst``, or deterministic tooling. Avoid adding agent-only project
+rules. If a rule matters for the project, document it where contributors can
+find it and let agents discover the same source.
+
+Deterministic enforcement
+-------------------------
+
+Prefer deterministic checks over prose-only instructions. When a convention can
+be enforced by a hacking check, linter, test fixture, or validation script, use
+that mechanism instead of relying on a person or an agent to remember prose.
+
+Minimal routing
+---------------
+
+Root ``AGENTS.md`` is a compact routing layer plus high-signal guardrails. It is
+not a tutorial, not a contributor guide, and not a replacement for the project
+documentation it links to. Keep it short enough that tools will read it and
+then follow its pointers to authoritative sources.
+
+AGENTS.md
+=========
+
+``AGENTS.md`` at the repository root provides terse routing pointers and a
+small set of guardrails for common incorrect actions. It should contain only
+information that is difficult for an agent to discover from source, config, or
+existing docs, and that is likely to prevent an incorrect action.
+
+Appropriate content includes:
+
+* pointers to authoritative contributor, testing, and subsystem docs;
+* guardrails for common incorrect actions not obvious from source or config;
+
+Avoid adding:
+
+* long-form explanations;
+* summaries of docs that may drift from the source of truth;
+* rules already enforced by ``tox -e pep8`` or other validation;
+* personal preferences or in-progress notes.
+
+When ``AGENTS.md`` approaches 100 lines, prune existing content before adding
+more, consolidating into contributor docs as required.
+
+Local scratch files
+===================
+
+Use ``.tmp/`` for local plans, scratch notes, generated prompts, and other
+ephemeral output from coding tools. The directory is gitignored and should not
+appear in upstream review history.
+
+Local tool configuration
+========================
+
+Local override files are tool-specific preferences. There is currently no
+standard format or name for a project-local override file. Some tools support
+files such as ``CLAUDE.local.md`` or ``AGENTS.override.md``; others use
+different names or do not support local instruction files. Configure these
+locally according to the tool being used.
+
+Do not assume another contributor's tool will read the same local files or use
+the same precedence rules. Shared project guidance belongs in the checked-in
+Nova docs and root ``AGENTS.md`` routing layer.
+
+Some tools do not natively support ``AGENTS.md`` and instead look for a
+tool-specific file at the repository root. For these tools, the recommended
+approach is a local symlink so that checked-in project guidance remains in
+``AGENTS.md`` without duplicating it.
+
+``CLAUDE.md`` is gitignored so contributors can maintain a personal file
+without it appearing in upstream review history. If a tool expects
+``CLAUDE.md`` at the root, create a local symlink::
+
+    ln -s AGENTS.md CLAUDE.md
+
+Tool invocation
+===============
+
+Assume project tools are installed and available on ``$PATH``. Invoke them
+directly in examples and automation, for example::
+
+    tox -e pep8
+
+Do not install tools system-wide with a package manager or ``pip`` (``apt
+install``, ``dnf install``, ``pip install``, ``pip install --user``, and
+similar). If a required Python tool is not on ``$PATH``, ``uvx`` or ``pipx
+run`` are acceptable ephemeral fallbacks. Do not use those wrappers as the
+primary invocation for project commands.
+
+Commit messages
+===============
+
+See :doc:`/contributor/commit-messages` for Nova commit message guidance,
+including Developer Certificate of Origin sign-off, Gerrit ``Change-Id``
+footers, and AI attribution trailers.

doc/source/contributor/commit-messages.rst

@@ -0,0 +1,84 @@
+.. _commit-messages:
+
+===============
+Commit Messages
+===============
+
+Nova follows the OpenStack Gerrit workflow. Commit messages should explain why
+the change is needed, be readable in email, and preserve the footers required by
+OpenStack tooling.
+
+For general OpenStack guidance, see the `OpenStack contributor guide commit
+message documentation`__ and the `OpenStack Git commit message wiki`__.
+
+.. __: https://docs.openstack.org/contributors/common/git.html#commit-messages
+.. __: https://wiki.openstack.org/wiki/GitCommitMessages
+
+Message style
+=============
+
+Use an imperative subject line, normally around 50 characters, with no trailing
+period. Wrap body text at 72 columns and explain why the change is needed, not
+just what changed.
+
+Use ASCII-safe printable characters in commit messages. Prefer ``<=``, ``>=``,
+``...``, and ``--`` rather than Unicode equivalents such as ``≤``, ``≥``,
+``…``, and ``—``. This keeps messages readable across terminals, mail clients,
+and review tools used in the OpenStack workflow.
+
+Gerrit Change-Id
+================
+
+Nova uses Gerrit. Do not remove existing ``Change-Id:`` footers when amending
+or rewording a commit. The ``Change-Id`` links new patch sets to the existing
+review.
+
+Developer Certificate of Origin
+===============================
+
+Nova follows the Linux Foundation Developer Certificate of Origin (DCO). Every
+commit must include a ``Signed-off-by:`` line certifying that the contributor
+has the right to submit the contribution::
+
+    Signed-off-by: Jane Smith <jane@example.com>
+
+When creating commits locally, ``git commit -s`` can add this footer.
+
+AI attribution trailers
+=======================
+
+When AI coding tools materially contribute to a Nova change, use one of the
+following trailers. The tool name is required. The model name or version is
+optional but should be included when known. Guidance matches the
+`OpenInfra Foundation policy for AI generated content`__.
+
+.. __: https://openinfra.dev/legal/ai-policy
+
+Notation: ``<x>`` = required, ``[x]`` = optional. Do not include the brackets
+or angle brackets in the final trailer.
+
+``Generated-By: <tool-name> [model-version]``
+    Use when the commit is mostly machine-authored with minimal human revision.
+
+``Assisted-By: <tool-name> [model-version]``
+    Use when a human materially revised, amended, or curated the AI-generated
+    work.
+
+When multiple AI tools materially contributed, each tool may have its own
+``Assisted-By`` or ``Generated-By`` trailer.
+
+Do not use ``Co-Authored-By:`` for AI tools. That trailer identifies human
+co-authors and carries a DCO implication; applying it to a language model
+misrepresents authorship. Use ``Generated-By`` or ``Assisted-By`` instead.
+
+Do not use ``Made-with:`` in this repository; Nova standardizes on
+``Generated-By`` and ``Assisted-By`` as described in that OpenInfra policy.
+
+Example footer block
+====================
+
+::
+
+    Assisted-By: my-agent my-model-v1
+    Signed-off-by: Jane Smith <jane@example.com>
+    Change-Id: I1234567890abcdef1234567890abcdef12345678

doc/source/contributor/dependencies.rst

@@ -0,0 +1,59 @@
+.. _dependencies:
+
+============
+Dependencies
+============
+
+Nova uses the standard OpenStack dependency management model. Keep dependency
+changes in the file that matches how the dependency is used so that local
+development, packaging, and CI jobs install the same inputs.
+
+Python dependencies
+===================
+
+Runtime Python dependencies belong in ``requirements.txt``. These are packages
+needed when Nova services or libraries run.
+
+Test-only Python dependencies belong in ``test-requirements.txt``. These are
+packages needed by unit, functional, and validation jobs but not by a deployed
+Nova service.
+
+Documentation-only Python dependencies belong in ``doc/requirements.txt``.
+These are packages needed to build or validate the documentation, such as
+Sphinx extensions, documentation themes, release note tooling, and redirect
+test tools.
+
+System packages
+===============
+
+Binary and operating-system package dependencies belong in ``bindep.txt``.
+Use bindep profiles such as ``test``, ``doc``, or ``pdf-docs`` when a package
+is only needed by a specific class of jobs. For example, a library or command
+needed only when building documentation should be listed in ``bindep.txt`` with
+the ``doc`` profile rather than documented as a manual setup step.
+
+Packaging metadata
+==================
+
+Nova uses ``pbr`` for Python packaging metadata. Do not introduce alternative
+version or dependency management systems such as ``setuptools-scm``. Keep
+package dependencies in the requirement files above so OpenStack constraints
+and CI can manage them consistently.
+
+``pyproject.toml`` is present and records static package metadata per
+`PEP 621`_, such as the project name, classifiers, and entry points. The
+version and main Python dependency list are dynamic and managed by ``pbr``;
+they are not edited in the ``dependencies`` table.
+
+Runtime, test, and documentation Python dependencies must continue to be
+declared in ``requirements.txt``, ``test-requirements.txt``, and
+``doc/requirements.txt`` as described above.
+
+Nova also defines a small set of setuptools extra groups in the
+``[project.optional-dependencies]`` table (for example ``osprofiler``,
+``zvm``, and ``vmware``). Use those only for the same driver or tooling
+extras already represented there. Do not add new general runtime or test
+dependencies via ``optional-dependencies``; add them to the appropriate
+requirement file instead.
+
+.. _PEP 621: https://peps.python.org/pep-0621/