diff --git a/.agents/README.md b/.agents/README.md index 8bacbdad6ed..68d095821e6 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -1,53 +1,16 @@ -# GPT-based coding agents +# Agent instructions -This repository supports OpenAI Codex alongside the existing Claude Code setup. -Instruction discovery belongs to the client, not the model: choosing a GPT -model in another client does not make that client read Codex configuration. +`AGENTS.md` files hold repository and directory guidance; `.agents/skills/` holds the shared skills. Keep skills client-agnostic: no argument variables or client-specific attribution. -Codex reads the root `AGENTS.md` and discovers skills under `.agents/skills/`. -No global configuration changes, plugins, or copied personal permissions are -required. Start Codex from this checkout and use `/skills` to browse, or invoke -a skill directly: +Claude Code reads neither location directly. Each `CLAUDE.md` is a one-line `@AGENTS.md` import, and each `.claude/skills/` is a symlink to `.agents/skills/`; add both when adding a nested `AGENTS.md` or a skill. -```text -$commit describe the staged changes -$pr target main -$review-pr -$rebase-onto-main -$build-px4 px4_fmu-v6xrt_default -``` - -Skills can also be selected from a matching natural-language request. GitHub -workflows require an authenticated `gh` CLI; container builds require Docker. -No model is pinned, so the instructions work with the GPT model selected in -your client. Restart Codex if newly added skills do not appear. - -## Shared guidance - -| Entry point | Source of workflow guidance | +| Skill | Use | | --- | --- | -| `AGENTS.md` | Repository conventions and references to `.github/instructions/` | -| `skills/commit/SKILL.md` | `.claude/skills/commit/SKILL.md` | -| `skills/pr/SKILL.md` | `.claude/skills/pr/SKILL.md` | -| `skills/review-pr/SKILL.md` | `.claude/skills/review-pr/SKILL.md` | -| `skills/rebase-onto-main/SKILL.md` | `.claude/skills/rebase-onto-main/SKILL.md` | -| `skills/build-px4/SKILL.md` | Self-contained container build workflow | -| `../docs/scripts/get_mode_requirements/AGENTS.md` | The generator's existing local `CLAUDE.md` | +| `commit` | Conventional commit with `Assisted-by:` trailer | +| `pr` | Pull request with Summary/Problem/Solution body | +| `review-pr` | PR review debrief and draft comment | +| `rebase-onto-main` | Rebase, including onto a squash-merged parent | +| `build-px4-linux` | Board or SITL build on a Linux host | +| `build-px4-macos` | Board build on macOS, in the `px4-dev` container | -The four adapters load the existing tracked workflow instead of maintaining -duplicate copies. Keep workflow changes in those shared source files; keep -Codex-specific invocation, tool, and attribution adjustments in the adapters. -References to `.claude/` are ordinary repository file reads, not a dependency -on having Claude Code installed. - -The build skill is self-contained because the existing local Claude build -skill is not tracked. It does not depend on local Claude settings, plans, -worktrees, or permissions. Agent-created build worktrees go under the ignored -`.agents/worktrees/` directory. - -Nested `AGENTS.md` files bridge existing directory-specific guidance without -duplicating it. The Claude entry points remain unchanged. - -See the official Codex documentation for -[AGENTS.md discovery](https://developers.openai.com/codex/guides/agents-md) and -[skills](https://developers.openai.com/codex/skills). +Create worktrees outside the repository, e.g. `../PX4-Autopilot-worktrees/`. diff --git a/.agents/skills/build-px4-linux/SKILL.md b/.agents/skills/build-px4-linux/SKILL.md new file mode 100644 index 00000000000..7b10c5467de --- /dev/null +++ b/.agents/skills/build-px4-linux/SKILL.md @@ -0,0 +1,46 @@ +--- +name: build-px4-linux +description: Build PX4 firmware or SITL natively on a Linux host, in the current checkout, without flashing hardware. +--- + +# Build PX4 on Linux + +## Inputs + +- A make target, for example `px4_fmu-v6x_default` or `px4_sitl`. Ask for it + if missing; validate it against `boards/`. + +Build the current checkout as-is, worktree or not. Do not create a worktree +or switch branches to build. + +## Prepare + +1. `arm-none-eabi-gcc --version` must succeed for NuttX targets. If it does + not, the host needs `Tools/setup/ubuntu.sh` (Ubuntu) — tell the user rather + than installing it, or build in the container: + `docker run --rm -w "$PWD" --user "$(id -u):$(id -g)" -v "$PWD:$PWD" px4io/px4-dev:v1.17.0 make `. + `Tools/docker_run.sh` passes `-it` and fails without a TTY. +2. The build initializes submodules itself; do not overwrite locally modified + ones. + +## Build + +```bash +set -o pipefail +make 2>&1 | tail -n 40 +``` + +Report failures with the output; never treat an existing artifact as +evidence of success. After changing a defconfig or Kconfig option, or +switching toolchains, `rm -rf build/` first: a stale build dir +recompiles nothing and links mixed objects. + +Do not run a NuttX build concurrently with `make tests` or SITL in the same +tree. + +## Report + +The artifact is `build//.px4` (NuttX) or +`build/px4_sitl_default/bin/px4` (SITL). Report the ref, commit, dirty state, +target, and artifact path. Building is not flashing; never upload without a +separate request. diff --git a/.agents/skills/build-px4/SKILL.md b/.agents/skills/build-px4-macos/SKILL.md similarity index 79% rename from .agents/skills/build-px4/SKILL.md rename to .agents/skills/build-px4-macos/SKILL.md index 85e9002d6f4..e5de27fd85b 100644 --- a/.agents/skills/build-px4/SKILL.md +++ b/.agents/skills/build-px4-macos/SKILL.md @@ -1,15 +1,14 @@ --- -name: build-px4 -description: Build PX4 board firmware in the px4-dev Docker container, including git worktrees, and stage commit-labeled artifacts without flashing hardware. +name: build-px4-macos +description: Build PX4 board firmware on macOS in the px4-dev Docker container, including git worktrees, and stage commit-labeled artifacts without flashing hardware. --- -# Build PX4 Firmware +# Build PX4 Firmware on macOS -Use this workflow for flashable board firmware, especially when a macOS host -lacks the NuttX toolchain. Use `px4io/px4-dev` container with the latest available -this container is a native cross-arch container. -It does not supply Gazebo or ROS 2. For Gazebo, use the repository's documented -host setup or a suitable simulator image instead. +Builds run in the multi-arch `px4io/px4-dev` container, so the host needs no +NuttX toolchain. If `Tools/setup/macos.sh` has been run (`arm-none-eabi-gcc` +on PATH), `make ` also works natively. The container has no Gazebo or +ROS 2; for simulation use the host setup in `docs/en/dev_setup/dev_env_mac.md`. ## Inputs @@ -30,14 +29,15 @@ a flashable `.px4` artifact. `docker image inspect px4io/px4-dev:v1.17.0`; pull it if missing. 4. Prefer an existing worktree for a requested ref. Otherwise resolve the ref (fetch its remote if necessary) and create a new detached worktree under - `.agents/worktrees/build-/` using `git worktree add --detach`. + `../PX4-Autopilot-worktrees/build-/`, outside the repository, + using `git worktree add --detach`. Reuse a path only after confirming its HEAD and working-tree state match the request. Never switch the user's active branch. 5. Check submodule status. Initialize required missing submodules, but do not overwrite locally modified submodules. -6. Inspect previous build artifacts if moving between macOS and Linux. Remove - only identified generated host binaries with an incompatible format or a - confirmed stale `build//` directory. Do not blindly clean source or +6. Inspect previous build artifacts if moving between native and container + builds. Remove only identified generated host binaries with an incompatible + format or a confirmed stale `build//` directory. Do not blindly clean source or user files. ## Build diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md index ecb3cf59da5..5d9923b5eed 100644 --- a/.agents/skills/commit/SKILL.md +++ b/.agents/skills/commit/SKILL.md @@ -1,20 +1,46 @@ --- name: commit -description: Create a PX4 conventional commit from reviewed changes with a topic-based scope and assistant disclosure. +description: Create a conventional commit for PX4 changes +argument-hint: "[optional: description of changes]" +allowed-tools: Bash Read Glob Grep --- # PX4 Conventional Commit -Read `.claude/skills/commit/SKILL.md` from the repository root and follow its -workflow with these substitutions: +Create a git commit in conventional-commit format: `type(scope): description`. -- Input is the user's request accompanying this skill, not literal `$ARGUMENTS`. -- Use the current client's tools rather than Claude-specific tool names. -- Replace `Assisted-by: Claude:` with - `Assisted-by: Codex:` when running in Codex. Use the actual client - name in other clients. If the model ID is unavailable, omit the colon and - model ID rather than inventing one. -- Preserve the user's authorship and the source workflow's DCO review - requirement. Follow any higher-priority client requirements for trailers. -- Stage only changes the user has authorized; never include unrelated dirty - submodules or untracked files. +- **type:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`, + `build`, `ci`, `chore`, `revert`. Append `!` before `:` for breaking changes. +- **scope:** the module/driver/area affected — derive from the directory + path of the changed files (`src/modules/ekf2/` → `ekf2`, + `src/drivers/imu/invensense/icm42688p/` → `drivers/icm42688p`, + `.github/workflows/` → `ci`). +- **description:** imperative, concise, ≥5 chars. + +**The user is the author. Never add `Co-Authored-By` naming an AI. End the +commit body with the disclosure trailer `Assisted-by: :` +(e.g. `Assisted-by: Claude:claude-fable-5`). Omit `:` rather than +invent one.** + +## Steps + +1. Check branch (`git branch --show-current`). If on `main`, create a feature + branch `/` where `` comes from + `gh api user --jq .login`. +2. Run `git status` and `git diff --staged`. If nothing staged, ask what to stage. +3. Run `make format` (or `./Tools/astyle/fix_code_style.sh `) on changed + C/C++ files. +4. Body (if needed): explain **why**, not what. +5. Commit with `git commit -s`. Do not pass `-S`: GPG signing is the user's + git config decision (`commit.gpgsign`), not the skill's. The `-s` sign-off + is the user's DCO certification of changes they have reviewed: never + commit with `-s` work the user has not seen. +6. Add new commits rather than amending pushed ones, and never force-push + unless the user asks or the branch is being rebased. PRs are squash-merged, + so the branch history costs nothing on `main` and shows reviewers the + decision chain. +7. If the branch has an upstream (`git rev-parse --abbrev-ref @{u}`), push. +8. If the branch has an open PR (`gh pr view --json state,body`), update its + description with `gh pr edit --body` when the commit changes what the + Summary, Problem, Solution or Testing sections say, following the `pr` + skill's format. Leave it alone otherwise. diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md index 1c04a541ddf..af9d0a5e8ec 100644 --- a/.agents/skills/pr/SKILL.md +++ b/.agents/skills/pr/SKILL.md @@ -1,18 +1,44 @@ --- name: pr -description: Create a PX4 pull request with a conventional title and concise Summary, Problem, and Solution sections. +description: Create a pull request with conventional commit title and description +argument-hint: "[optional: target branch or description]" +allowed-tools: Bash Read Glob Grep --- # PX4 Pull Request -Read `.claude/skills/pr/SKILL.md` from the repository root and follow its -workflow with these substitutions: +**The user is the author: no `Co-Authored-By`, no "Generated with " +footers. Disclose AI assistance with `Assisted-by: :` as the +last line of the PR body, as in the commit trailers.** -- Input is the user's request accompanying this skill, not literal `$ARGUMENTS`. -- Use the current client's tools rather than Claude-specific tool names. -- Apply the source's ban on Claude attribution to generated-by footers for - any assistant. Keep disclosure in commit trailers, not the PR body. -- If a firmware build is needed, read `.agents/skills/build-px4/SKILL.md`. - Choose a target affected by the change; do not build for documentation-only - changes or imply that a build proves flight safety. -- Use `gh` for GitHub operations and return the created PR URL. +## Steps + +1. Check branch. If on `main`, create a feature branch `/` + where `` comes from `gh api user --jq .login`. +2. Gather context: `git status`, `git log --oneline main..HEAD`, + `git diff main...HEAD --stat`, check for remote tracking branch. +3. Sanity-build **one** target the change can actually affect — a board for + firmware changes, `px4_sitl` for POSIX-only or simulation changes. Skip the + build entirely when the diff cannot reach any target (submodule pointer + bumps, docs, ROMFS). Build with the `build-px4-linux` or `build-px4-macos` + skill. Fix any build errors before opening the PR. +4. PR **title:** `type(scope): description` — under 72 chars, covers the + overall change across all commits. This becomes the squash-merge commit + message. +5. PR **body:** as short as it can be while still landing the point — a + reviewer should take it in at a glance, and a long description is one + nobody reads. Sections, in order: `## Summary`, `## Problem`, + `## Solution`, a sentence or two each. Do not restate the diff (no + file-changed lists, no code snippets), do not mention CI, and do not repeat + what the title already says. If the PR closes an issue, the first line of + `## Summary` is `fixes #`, then a blank line, then the summary. No + boilerplate. +6. Optional `## Testing` section after `## Solution`, only for substantial + testing: SITL scenarios, synthetic or replayed data, hardware-in-the-loop, + bench or flight tests. Building and unit tests are not testing; never + mention them. State what was run and what it showed, as tersely as the + other sections. Never report testing that did not happen: ask the user + what they actually ran. +7. Push with `-u` if needed, then `gh pr create`. Default base is `main` + unless user says otherwise. +8. Return the PR URL. diff --git a/.agents/skills/rebase-onto-main/SKILL.md b/.agents/skills/rebase-onto-main/SKILL.md index c637908e3c1..516ef2a13ca 100644 --- a/.agents/skills/rebase-onto-main/SKILL.md +++ b/.agents/skills/rebase-onto-main/SKILL.md @@ -1,26 +1,102 @@ --- name: rebase-onto-main -description: Rebase a PX4 branch onto main, handling squash-merged parent branches without replaying inherited commits. +description: Rebase a branch onto main, handling squash-merged parent branches cleanly +argument-hint: "[optional: branch name, defaults to current branch]" +allowed-tools: Bash Read Glob Grep Agent --- # Rebase Branch onto Main -Read `.claude/skills/rebase-onto-main/SKILL.md` from the repository root and -follow its workflow with these adaptations: +Rebase the current (or specified) branch onto `main`, correctly handling the case where the branch was built on top of another branch that has since been squash-merged into `main`. -- Input is the branch in the user's request, defaulting to the current branch. - Do not interpret `$ARGUMENTS` as a shell variable. -- Use available tools; ignore claims about Claude's Bash execution environment. - Explicitly check checkout and rebase failures regardless of shell behavior. -- Inspect the working tree and worktrees first. Preserve unrelated changes and - run in the worktree that owns the branch. Do not automatically stash user work. -- If `main` is checked out in another worktree, fetch `origin main` and use - `origin/main` as the new base rather than updating that checked-out branch. -- Record the old head and the unique-commit boundary before rewriting history. - For a squash-merged parent, compare only the branch's unique commits in - `git range-diff ^.. ..`. - Inherited commits intentionally excluded from the replay are not lost work. - Investigate any changed, missing, or added unique patch before proceeding. -- Keep a backup ref until the result has been reviewed. Ask before force-pushing - and use only `--force-with-lease`. Do not rewrite or push dependent branches - without authorization. +## Background + +When a parent branch is squash-merged, its individual commits become a single new commit on `main` with a different hash. A normal `git rebase main` will try to replay the parent's original commits, causing messy conflicts. The fix is to **cherry-pick only the commits unique to this branch** onto a fresh branch from `main`. + +## Steps + +1. **Identify the branch.** Use the branch the user named, otherwise the current branch. + + Check `git worktree list` first. A branch checked out in another worktree cannot be checked out here — `git checkout` fails with `fatal: '' is already used by worktree at ...`. Rebase it in place instead: `git -C rebase main`. + + When rebasing several branches in a loop, test the checkout's exit status explicitly: + + ``` + git checkout -q "$b" || { echo "SKIP $b (worktree?)"; continue; } + ``` + + Without that guard the loop rebases whatever is *currently* checked out, once per failed iteration, and reports success — the rebase really did work, just on the wrong branch. `set -e` is not a substitute: it is ignored in an agent's Bash tool call (it only takes effect when bash runs a script file). + +2. **Fetch and update main:** + ``` + git fetch origin main:main + ``` + +3. **Find the merge base** between the branch and `main`: + ``` + git merge-base main + ``` + +4. **List all commits** on the branch since the merge base: + ``` + git log --oneline .. + ``` + +5. **Identify which commits are unique to this branch** vs. inherited from a parent branch. Look for: + - Squash-merged commits on `main` that correspond to a group of commits at the bottom of the branch's history (check PR titles, commit message keywords). + - The boundary commit: the first commit that belongs to *this* branch's work, not the parent's. + - If ALL commits are unique (no parent branch), just do a normal `git rebase main` and skip the rest. + +6. **Create a fresh branch from `main`:** + ``` + git checkout -b -rebase main + ``` + +7. **Cherry-pick only the unique commits** (oldest first): + ``` + git cherry-pick ^.. + ``` + The `A^..B` range means "from the parent of A through B inclusive." + +8. **Handle conflicts** if any arise during cherry-pick. Resolve and `git cherry-pick --continue`. + +9. **Replace the old branch:** + ``` + git branch -m -old + git branch -m -rebase + ``` + +10. **Verify** the result: + ``` + git log --oneline main.. + ``` + Confirm only the expected commits are present. + + Then prove no content changed, because the next step overwrites the only copy of the old head: + ``` + git range-diff .. main.. + ``` + Every line must be marked `=` (identical patch). `!` means a commit's diff changed, `<` means one was dropped, `>` means one appeared. Anything but `=` is a rebase that lost or altered work — stop and look before pushing. Scripted: + ``` + rd=$(git range-diff --no-color .. main..) + tot=$(echo "$rd" | grep -cE '^ *[0-9]+:') + eq=$(echo "$rd" | grep -cE '^ *[0-9]+: +[0-9a-f]+ = ') + [ "$tot" = "$eq" ] && echo CLEAN || echo REVIEW + ``` + +11. **Ask the user** before force-pushing. When approved: + ``` + git push origin --force-with-lease + ``` + Use `--force-with-lease`, never a bare `--force`. Push to the remote that holds the branch's PR head. + + If this branch is the base of a stacked PR, the branch above it still points at the pre-rebase commits. Rebase it onto the new head and force-push it too: + ``` + git rebase --onto + ``` + Skipping this makes the upper PR show every commit on `main`. + +12. **Clean up** the old branch: + ``` + git branch -D -old + ``` diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md index ddc504e5a6a..87704ba1482 100644 --- a/.agents/skills/review-pr/SKILL.md +++ b/.agents/skills/review-pr/SKILL.md @@ -1,21 +1,57 @@ --- name: review-pr -description: Review a PX4 pull request for engineering merit, first-principles correctness, and architecture fit; deliver a debrief and an unpublished draft. +description: Substance-focused review of a PX4 pull request — merit, first-principles correctness, architecture fit. Produces a debrief for the user and a draft review comment. +argument-hint: "" +allowed-tools: Bash Read Glob Grep Agent --- # PX4 Pull Request Review -Read `.claude/skills/review-pr/SKILL.md` from the repository root and follow -its workflow with these substitutions: +Goal: brief the user on a PR before they spend their own time on it, and draft a review comment they can choose to post. The review is by the assistant and is presented as such — write from its own frame of reference, not the user's, unless the user explicitly requests a different voice. -- Input is the PR number or URL in the user's request, not literal `$ARGUMENTS`. -- Use the current client's tools. Delegate independent subsystem investigations - only when subagents are available and the scope warrants them; otherwise - investigate directly. -- Write from the actual assistant's perspective, not Claude's or the user's. - In Codex, the draft's first line is - `**Codex review on behalf of @**`. Use the actual client name elsewhere; - obtain the login with `gh api user --jq .login` as in the source workflow. -- Read the applicable `.github/instructions/` guidance referenced by `AGENTS.md`. -- Deliver both the debrief and fenced draft. Do not post the draft unless - explicitly requested. +Focus on substance only. Do not review commit messages, do not recommend a merge strategy, do not audit formatting (CI enforces it). Be extremely thorough — the user wants a deep understanding of the problem, not just verdicts — but scale effort with impact: roughly proportional to lines/files changed and how flight-critical the touched code is. For diffs too large to hold at once, fan out subagents per subsystem when the client has them. + +## Gather + +In parallel: + +- `gh pr view --json number,title,body,author,baseRefName,files,reviews` +- `gh pr diff ` — on HTTP 406 (huge diff) do not retry; use `gh api repos/{owner}/{repo}/pulls//files --paginate` and fetch key patches selectively +- `gh pr checks ` (exit code 8 just means checks are pending) +- existing feedback: `gh api repos/{owner}/{repo}/pulls//comments --paginate --jq '.[] | {user: .user.login, path, body}'` (inline) and `gh api repos/{owner}/{repo}/issues//comments --paginate --jq '.[] | {user: .user.login, body}'` (conversation) + +Read any linked issue — the claimed problem is the baseline for judging merit. For full post-change file contents without touching the working tree: `git fetch origin pull//head`, then `git show FETCH_HEAD:`. + +## History (optional) + +When the PR changes existing behavior rather than adding something new, check whether the author has done their homework on the area: + +- Open issues and PRs touching the same code or symptom: `gh issue list --search`, `gh pr list --search`. Is this already being worked on, or duplicated? +- `git log -L` / `git log --follow -p` and `git blame` on the changed lines, then the PRs and issues those commits reference. Was the current behavior intentional, and was the reasoning sound? +- Deferred work: TODOs, issue threads, or review comments where the change was considered and deliberately postponed or rejected. + +Report only what bears on the PR: a reverted decision the author does not acknowledge, conflicting in-flight work, or an unaddressed reason the code is the way it is. + +## Review + +Never judge a hunk from the diff alone. Read the enclosing function and file, and grep for callers and consumers — a PR is always reviewed in the context of the surrounding code. + +- **Merit and need.** Is this solving a real problem or papering over one? Trace the failure mechanism; check the fix addresses the root cause at the right layer. Ask whether a simpler change (different default, existing parameter, deleting code) would achieve the same. +- **Physics and math.** If the change involves physics, estimation, control, or nontrivial math, do a first-principles analysis: re-derive the result and check the implementation against your derivation, not against the PR description. Verify units, reference frames (FRD/NED, body/earth), signs, singularities and edge cases (division by zero, gimbal lock, low airspeed), timestep/discretization dependence, and numerical robustness in the given representation (NaN propagation, cancellation, float32 precision limits). +- **Architecture and maintainability.** Does the change follow the patterns of the code around it (uORB usage, scheduling, param handling, data ownership)? Does it reimplement something an existing library provides (AlphaFilter, SlewRate, mathlib)? Does the logic live in the module that owns the data? Watch for hidden coupling — a change that silently breaks an assumption in another module; if cross-module coupling is genuinely necessary, expect a unit test that codifies the new contract and fails if it is later broken. Embedded reality: flash is scarce, no dynamic allocation in flight code, mind CPU cost. +- **Alternatives.** Identify plausible alternative implementations and judge each: better, worse, or not worth mentioning. Raise only the ones the author should genuinely consider, and say why. +- **Correctness and reliability.** Edge cases, overflow, unsigned arithmetic, initialization, bounds, races, resource exhaustion, and failure-path handling. Flag real defects, not style. +- **Compatibility.** Changes to `msg/`, params, or MAVLink: impact on QGC, uLog tooling, and third-party integrations. uORB: `timestamp` vs `timestamp_sample`, `device_id`. Every new parameter is configuration burden on users — challenge it. +- **New board** (`boards///`): require a logs.px4.io flight log for the vehicle type, a docs page in `docs/en/flight_controller/`, the manufacturer's own USB VID/PID, a unique board_id in `boards.json`, CI build coverage, flash fit, and no copy-pasted template leftovers or board-local forks of common drivers. + +Also, briefly: the PR title must be `type(scope): description` (it becomes the commit subject on squash); note CI status and read failure logs only when plausibly related to the change; do not repeat feedback other reviewers already gave — build on it or stay silent. + +## Deliver + +End with two things, then stop — do not post anything. + +**1. Debrief for the user.** Lead with the findings — the user wants actionable information, not a play-by-play of the diff. Give only the framing they need to judge the change: whether the claimed problem is real, scope and risk (subsystems touched, flight-critical or not), and what CI and other reviewers already said. Restate what the change actually does and why only when the PR description is missing, ambiguous, or misleading. Order findings by severity (blocker / concern / nit) with `file:line`. + +**2. Draft review comment**, shown verbatim in a fenced block. First line: `** review on behalf of @**` (e.g. `Claude`, `Codex`) (login via `gh api user --jq .login`). Then terse, actionable findings only — what is wrong, why it matters, what to do, with file:line references. Frame each as an objective engineering tradeoff, not a moral judgment. Never guess: if you cannot demonstrate a flaw via a concrete code path or a first-principles derivation, stay silent. No praise or "verified OK" notes unless they change what the author should do, no meta sections, no conversational filler, nothing already raised by others. + +If the user asks to post it, post the draft verbatim with `gh pr comment --body "$(cat <<'EOF' ... EOF)"`. diff --git a/.claude/skills/build-px4-linux b/.claude/skills/build-px4-linux new file mode 120000 index 00000000000..947d2c0c430 --- /dev/null +++ b/.claude/skills/build-px4-linux @@ -0,0 +1 @@ +../../.agents/skills/build-px4-linux \ No newline at end of file diff --git a/.claude/skills/build-px4-macos b/.claude/skills/build-px4-macos new file mode 120000 index 00000000000..44ce730f6f9 --- /dev/null +++ b/.claude/skills/build-px4-macos @@ -0,0 +1 @@ +../../.agents/skills/build-px4-macos \ No newline at end of file diff --git a/.claude/skills/commit b/.claude/skills/commit new file mode 120000 index 00000000000..c237c5b8d88 --- /dev/null +++ b/.claude/skills/commit @@ -0,0 +1 @@ +../../.agents/skills/commit \ No newline at end of file diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md deleted file mode 100644 index 190a54a3d7a..00000000000 --- a/.claude/skills/commit/SKILL.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: commit -description: Create a conventional commit for PX4 changes -argument-hint: "[optional: description of changes]" -allowed-tools: Bash, Read, Glob, Grep ---- - -# PX4 Conventional Commit - -Create a git commit in conventional-commit format: `type(scope): description`. - -- **type:** `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`, - `build`, `ci`, `chore`, `revert`. Append `!` before `:` for breaking changes. -- **scope:** the module/driver/area affected — derive from the directory - path of the changed files (`src/modules/ekf2/` → `ekf2`, - `src/drivers/imu/invensense/icm42688p/` → `drivers/icm42688p`, - `.github/workflows/` → `ci`). -- **description:** imperative, concise, ≥5 chars. - -**The user is the author. Never add `Co-Authored-By` naming an AI. End the -commit body with the disclosure trailer `Assisted-by: Claude:` -(e.g. `Assisted-by: Claude:claude-fable-5`).** - -## Steps - -1. Check branch (`git branch --show-current`). If on `main`, create a feature - branch `/` where `` comes from - `gh api user --jq .login`. -2. Run `git status` and `git diff --staged`. If nothing staged, ask what to stage. -3. Run `make format` (or `./Tools/astyle/fix_code_style.sh `) on changed - C/C++ files. -4. Body (if needed): explain **why**, not what. -5. Commit with `git commit -s`. Do not pass `-S`: GPG signing is the user's - git config decision (`commit.gpgsign`), not the skill's. The `-s` sign-off - is the user's DCO certification of changes they have reviewed: never - commit with `-s` work the user has not seen. - -If the user provided arguments, use them as context: $ARGUMENTS diff --git a/.claude/skills/pr b/.claude/skills/pr new file mode 120000 index 00000000000..8ea58ab6a85 --- /dev/null +++ b/.claude/skills/pr @@ -0,0 +1 @@ +../../.agents/skills/pr \ No newline at end of file diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md deleted file mode 100644 index ce31bfeba0a..00000000000 --- a/.claude/skills/pr/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: pr -description: Create a pull request with conventional commit title and description -argument-hint: "[optional: target branch or description]" -allowed-tools: Bash, Read, Glob, Grep ---- - -# PX4 Pull Request - -**The user is the author: no `Co-Authored-By`, no "Generated with Claude" -footers. AI disclosure lives in the commit trailers (`Assisted-by:`), not in -the PR body.** - -## Steps - -1. Check branch. If on `main`, create a feature branch `/` - where `` comes from `gh api user --jq .login`. -2. Gather context: `git status`, `git log --oneline main..HEAD`, - `git diff main...HEAD --stat`, check for remote tracking branch. -3. Sanity-build **one** target the change can actually affect — a board for - firmware changes, `px4_sitl` for POSIX-only or simulation changes. Skip the - build entirely when the diff cannot reach any target (submodule pointer - bumps, docs, ROMFS). Fix any build errors before opening the PR. -4. PR **title:** `type(scope): description` — under 72 chars, covers the - overall change across all commits. This becomes the squash-merge commit - message. -5. PR **body:** as short as it can be while still landing the point — a - reviewer should take it in at a glance, and a long description is one - nobody reads. Exactly three sections, in order: `## Summary`, `## Problem`, - `## Solution`, a sentence or two each. Do not restate the diff (no - file-changed lists, no code snippets), do not mention CI, and do not repeat - what the title already says. If the PR closes an issue, the first line of - `## Summary` is `fixes #`, then a blank line, then the summary. No - `## Test plan` section, no boilerplate, no Claude attribution. Never state - testing that did not happen: ask the user what they actually ran, report - exactly that, and say plainly when something is untested. - -6. Push with `-u` if needed, then `gh pr create`. Default base is `main` - unless user says otherwise. -7. Return the PR URL. - -If the user provided arguments, use them as context: $ARGUMENTS diff --git a/.claude/skills/rebase-onto-main b/.claude/skills/rebase-onto-main new file mode 120000 index 00000000000..15a63dcb940 --- /dev/null +++ b/.claude/skills/rebase-onto-main @@ -0,0 +1 @@ +../../.agents/skills/rebase-onto-main \ No newline at end of file diff --git a/.claude/skills/rebase-onto-main/SKILL.md b/.claude/skills/rebase-onto-main/SKILL.md deleted file mode 100644 index be58355da58..00000000000 --- a/.claude/skills/rebase-onto-main/SKILL.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -name: rebase-onto-main -description: Rebase a branch onto main, handling squash-merged parent branches cleanly -argument-hint: "[optional: branch name, defaults to current branch]" -allowed-tools: Bash, Read, Glob, Grep, Agent ---- - -# Rebase Branch onto Main - -Rebase the current (or specified) branch onto `main`, correctly handling the case where the branch was built on top of another branch that has since been squash-merged into `main`. - -## Background - -When a parent branch is squash-merged, its individual commits become a single new commit on `main` with a different hash. A normal `git rebase main` will try to replay the parent's original commits, causing messy conflicts. The fix is to **cherry-pick only the commits unique to this branch** onto a fresh branch from `main`. - -## Steps - -1. **Identify the branch.** Use `$ARGUMENTS` if provided, otherwise use the current branch. - - Check `git worktree list` first. A branch checked out in another worktree cannot be checked out here — `git checkout` fails with `fatal: '' is already used by worktree at ...`. Rebase it in place instead: `git -C rebase main`. - - When rebasing several branches in a loop, test the checkout's exit status explicitly: - - ``` - git checkout -q "$b" || { echo "SKIP $b (worktree?)"; continue; } - ``` - - Without that guard the loop rebases whatever is *currently* checked out, once per failed iteration, and reports success — the rebase really did work, just on the wrong branch. `set -e` is not a substitute: it is ignored in a Claude Code Bash tool call (it only takes effect when bash runs a script file). - -2. **Fetch and update main:** - ``` - git fetch origin main:main - ``` - -3. **Find the merge base** between the branch and `main`: - ``` - git merge-base main - ``` - -4. **List all commits** on the branch since the merge base: - ``` - git log --oneline .. - ``` - -5. **Identify which commits are unique to this branch** vs. inherited from a parent branch. Look for: - - Squash-merged commits on `main` that correspond to a group of commits at the bottom of the branch's history (check PR titles, commit message keywords). - - The boundary commit: the first commit that belongs to *this* branch's work, not the parent's. - - If ALL commits are unique (no parent branch), just do a normal `git rebase main` and skip the rest. - -6. **Create a fresh branch from `main`:** - ``` - git checkout -b -rebase main - ``` - -7. **Cherry-pick only the unique commits** (oldest first): - ``` - git cherry-pick ^.. - ``` - The `A^..B` range means "from the parent of A through B inclusive." - -8. **Handle conflicts** if any arise during cherry-pick. Resolve and `git cherry-pick --continue`. - -9. **Replace the old branch:** - ``` - git branch -m -old - git branch -m -rebase - ``` - -10. **Verify** the result: - ``` - git log --oneline main.. - ``` - Confirm only the expected commits are present. - - Then prove no content changed, because the next step overwrites the only copy of the old head: - ``` - git range-diff .. main.. - ``` - Every line must be marked `=` (identical patch). `!` means a commit's diff changed, `<` means one was dropped, `>` means one appeared. Anything but `=` is a rebase that lost or altered work — stop and look before pushing. Scripted: - ``` - rd=$(git range-diff --no-color .. main..) - tot=$(echo "$rd" | grep -cE '^ *[0-9]+:') - eq=$(echo "$rd" | grep -cE '^ *[0-9]+: +[0-9a-f]+ = ') - [ "$tot" = "$eq" ] && echo CLEAN || echo REVIEW - ``` - -11. **Ask the user** before force-pushing. When approved: - ``` - git push origin --force-with-lease - ``` - Use `--force-with-lease`, never a bare `--force`. Push to the remote that holds the branch's PR head. - - If this branch is the base of a stacked PR, the branch above it still points at the pre-rebase commits. Rebase it onto the new head and force-push it too: - ``` - git rebase --onto - ``` - Skipping this makes the upper PR show every commit on `main`. - -12. **Clean up** the old branch: - ``` - git branch -D -old - ``` diff --git a/.claude/skills/review-pr b/.claude/skills/review-pr new file mode 120000 index 00000000000..effc6b72583 --- /dev/null +++ b/.claude/skills/review-pr @@ -0,0 +1 @@ +../../.agents/skills/review-pr \ No newline at end of file diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md deleted file mode 100644 index 91780fde195..00000000000 --- a/.claude/skills/review-pr/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: review-pr -description: Substance-focused review of a PX4 pull request — merit, first-principles correctness, architecture fit. Produces a debrief for the user and a draft review comment. -argument-hint: "" -allowed-tools: Bash, Read, Glob, Grep, Agent ---- - -# PX4 Pull Request Review - -Goal: brief the user on a PR before they spend their own time on it, and draft a review comment they can choose to post. The review is by Claude and is presented as such — write from Claude's frame of reference, not the user's, unless the user explicitly requests a different voice. - -Focus on substance only. Do not review commit messages, do not recommend a merge strategy, do not audit formatting (CI enforces it). Be extremely thorough — the user wants a deep understanding of the problem, not just verdicts — but scale effort with impact: roughly proportional to lines/files changed and how flight-critical the touched code is. For diffs too large to hold at once, fan out Explore agents per subsystem. - -## Gather - -In parallel: - -- `gh pr view --json number,title,body,author,baseRefName,files,reviews` -- `gh pr diff ` — on HTTP 406 (huge diff) do not retry; use `gh api repos/{owner}/{repo}/pulls//files --paginate` and fetch key patches selectively -- `gh pr checks ` (exit code 8 just means checks are pending) -- existing feedback: `gh api repos/{owner}/{repo}/pulls//comments --paginate --jq '.[] | {user: .user.login, path, body}'` (inline) and `gh api repos/{owner}/{repo}/issues//comments --paginate --jq '.[] | {user: .user.login, body}'` (conversation) - -Read any linked issue — the claimed problem is the baseline for judging merit. For full post-change file contents without touching the working tree: `git fetch origin pull//head`, then `git show FETCH_HEAD:`. - -## Review - -Never judge a hunk from the diff alone. Read the enclosing function and file, and grep for callers and consumers — a PR is always reviewed in the context of the surrounding code. - -- **Merit and need.** Is this solving a real problem or papering over one? Trace the failure mechanism; check the fix addresses the root cause at the right layer. Ask whether a simpler change (different default, existing parameter, deleting code) would achieve the same. -- **Physics and math.** If the change involves physics, estimation, control, or nontrivial math, do a first-principles analysis: re-derive the result and check the implementation against your derivation, not against the PR description. Verify units, reference frames (FRD/NED, body/earth), signs, singularities and edge cases (division by zero, gimbal lock, low airspeed), timestep/discretization dependence, and numerical robustness in the given representation (NaN propagation, cancellation, float32 precision limits). -- **Architecture and maintainability.** Does the change follow the patterns of the code around it (uORB usage, scheduling, param handling, data ownership)? Does it reimplement something an existing library provides (AlphaFilter, SlewRate, mathlib)? Does the logic live in the module that owns the data? Watch for hidden coupling — a change that silently breaks an assumption in another module; if cross-module coupling is genuinely necessary, expect a unit test that codifies the new contract and fails if it is later broken. Embedded reality: flash is scarce, no dynamic allocation in flight code, mind CPU cost. -- **Alternatives.** Identify plausible alternative implementations and judge each: better, worse, or not worth mentioning. Raise only the ones the author should genuinely consider, and say why. -- **Correctness and reliability.** Edge cases, overflow, unsigned arithmetic, initialization, bounds, races, resource exhaustion, and failure-path handling. Flag real defects, not style. -- **Compatibility.** Changes to `msg/`, params, or MAVLink: impact on QGC, uLog tooling, and third-party integrations. uORB: `timestamp` vs `timestamp_sample`, `device_id`. Every new parameter is configuration burden on users — challenge it. -- **New board** (`boards///`): require a logs.px4.io flight log for the vehicle type, a docs page in `docs/en/flight_controller/`, the manufacturer's own USB VID/PID, a unique board_id in `boards.json`, CI build coverage, flash fit, and no copy-pasted template leftovers or board-local forks of common drivers. - -Also, briefly: the PR title must be `type(scope): description` (it becomes the commit subject on squash); note CI status and read failure logs only when plausibly related to the change; do not repeat feedback other reviewers already gave — build on it or stay silent. - -## Deliver - -End with two things, then stop — do not post anything. - -**1. Debrief for the user.** Lead with the findings — the user wants actionable information, not a play-by-play of the diff. Give only the framing they need to judge the change: whether the claimed problem is real, scope and risk (subsystems touched, flight-critical or not), and what CI and other reviewers already said. Restate what the change actually does and why only when the PR description is missing, ambiguous, or misleading. Order findings by severity (blocker / concern / nit) with `file:line`, and end with a one-or-two-sentence overall take. - -**2. Draft review comment**, shown verbatim in a fenced block. First line: `**Claude review on behalf of @**` (login via `gh api user --jq .login`). Then terse, actionable findings only — what is wrong, why it matters, what to do, with file:line references. Frame each as an objective engineering tradeoff, not a moral judgment. Never guess: if you cannot demonstrate a flaw via a concrete code path or a first-principles derivation, stay silent. No praise or "verified OK" notes unless they change what the author should do, no meta sections, no conversational filler, nothing already raised by others. - -If the user asks to post it, post the draft verbatim with `gh pr comment --body "$(cat <<'EOF' ... EOF)"`. - -PR to review: $ARGUMENTS diff --git a/.gitignore b/.gitignore index d2419c20947..4733d3961bc 100644 --- a/.gitignore +++ b/.gitignore @@ -117,8 +117,6 @@ _emscripten_sdk/ # virtual Python environment .venv -# Claude Code local settings +# Claude Code local settings and worktrees .claude/settings.local.json - -# Agent-created build worktrees -/.agents/worktrees/ +/.claude/worktrees/ diff --git a/AGENTS.md b/AGENTS.md index efc0775086f..7538b88e658 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,11 +3,14 @@ Safety-critical C/C++ flight control firmware for autopilots, plus SITL simulation and Python tooling. -- **Commits:** use the `$commit` skill. Conventional commit format with +- **Commits:** use the `commit` skill. Conventional commit format with topic-based scope: `type(scope): description`. -- **Pull requests:** use the `$pr` skill. -- **Attribution:** use the actual assistant identity, never Claude's when - running another client. No generated-by footer in PR bodies. +- **Pull requests:** use the `pr` skill. +- **Builds:** use the `build-px4-linux` or `build-px4-macos` skill for the + host OS. +- **Attribution:** disclose AI assistance only in the `Assisted-by:` commit + trailer. No `Co-Authored-By` naming an AI, no generated-by footer in PR + bodies. - **Style:** run `make format` on changed C/C++ before committing; CI enforces `make check_format`. - **Scoped guidance:** before editing or reviewing, read only the diff --git a/CLAUDE.md b/CLAUDE.md index 88355ff8b81..43c994c2d36 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,12 +1 @@ -# PX4-Autopilot - -Safety-critical C/C++ flight control firmware for autopilots, plus SITL -simulation and Python tooling. - -- **Commits:** use the `/commit` skill. Conventional commit format with - topic-based scope: `type(scope): description`. -- **Pull requests:** use the `/pr` skill. -- **No Claude attribution** — no `Co-Authored-By: Claude`, no "Generated - with Claude Code" footer. -- **Style:** run `make format` on changed C/C++ before committing; CI - enforces `make check_format`. +@AGENTS.md diff --git a/docs/scripts/get_mode_requirements/AGENTS.md b/docs/scripts/get_mode_requirements/AGENTS.md index 665131041d8..f44f3142a5f 100644 --- a/docs/scripts/get_mode_requirements/AGENTS.md +++ b/docs/scripts/get_mode_requirements/AGENTS.md @@ -1,11 +1,219 @@ # get_mode_requirements -Before changing files in this directory, read the sibling -[CLAUDE.md](CLAUDE.md) and follow its generator-specific instructions. -That file is the shared source of truth for parser behavior, generated-content -boundaries, metadata ordering, and golden-file tests; it applies regardless of -which assistant or model is being used. +## Purpose -In particular, do not hand-edit generated sentinel blocks in `docs/en/`. -Change the generator inputs instead, and follow the documented test and -golden-file update workflow for intentional behavior changes. +`get_mode_requirements.py` parses the PX4 flight mode requirements defined in +`src/modules/commander/ModeUtil/mode_requirements.cpp` and generates Markdown documentation. + +It produces two kinds of output under `docs/en/`: + +- `flight_modes/mode_requirements.md` — a consolidated overview table for all vehicle types. +- Per-mode requirement text injected directly into individual flight-mode pages using include markers. + +## Running + +From the repo root: + +```sh +python3 docs/scripts/get_mode_requirements/get_mode_requirements.py +``` + +Or from the `docs/` directory: + +```sh +python3 scripts/get_mode_requirements/get_mode_requirements.py +``` + +## Inline Injection + +The script locates each parent flight-mode doc (e.g. `flight_modes_fw/manual.md`) by scanning +`docs/en/flight_modes/`, `docs/en/flight_modes_fw/`, `docs/en/flight_modes_mc/`, and +`docs/en/advanced_features/` for a VitePress `` directive (or an existing +`AUTO-GENERATED` sentinel block) that references the corresponding snippet name +(`build_snippet_to_parent_map()`). This directory scan is what actually determines where a +mode's requirements get injected — it is **independent** of the `doc` field in +`mode_nav_state_defns.json`, which only controls headings/links in `mode_requirements.md`. A +mode can have a `doc` pointing at a page that isn't scanned (or has no injection marker on it +yet) and still trigger a "not mapped to a doc" warning; fix this by adding an +`` marker pair +(content between them can be empty — the script fills it in) to the actual doc page, and if +that page lives outside the four scanned directories, add its directory to `search_dirs` in +`build_snippet_to_parent_map()`. + +A single doc page can contain multiple injection points for different nav-states (e.g. +`flight_modes/offboard.md` has one per vehicle type; `flight_modes_mc/manual_stabilized.md` +has one for `NAVIGATION_STATE_STAB` and one for `NAVIGATION_STATE_MANUAL`, since those are +distinct nav-states with different requirements that happen to share one doc page). Each +generated block always starts its own `### Mode Requirements` heading, so when adding a second +block to the same page, add distinguishing surrounding text/labels manually to avoid duplicate +headings, then hand-write the marker pair; the script replaces the content and heading between +the markers. + +It replaces that directive with the rendered content, wrapped in sentinel HTML comments: + +```markdown + +### Mode Requirements + +The following requirements must be met to arm in this mode, or to switch to this mode when it is armed. + +- [`mode_req_manual_control`](xxx) - Requires stick input + + +``` + +On subsequent runs the sentinels are detected and the content between them is updated in-place, +so the script is safe to re-run whenever `mode_requirements.cpp` changes. + +**Do not edit the text between the sentinel comments manually** — it will be overwritten on the +next run. Make changes in `requirement_defns.json` or in `mode_requirements.cpp`. + +## Path Calculation + +The script resolves the repository root at runtime using `Path(__file__).resolve()` and +navigating **three** parent directories up: + +``` +docs/scripts/get_mode_requirements/get_mode_requirements.py + -> docs/scripts/get_mode_requirements/ (parent) + -> docs/scripts/ (parent.parent) + -> docs/ (parent.parent.parent) + -> PX4-Autopilot/ (parent.parent.parent.parent) ← repo root +``` + +If this script is ever moved, update the `repo_root` line accordingly. + +## Adding or Changing Requirement Definitions + +`requirement_defns.json` (in the same directory as the script) maps each `mode_req_*` flag +name to a human-readable `text`, an example `sensor`, and an extended `detail` string. Add +new entries here when new requirement flags are introduced in `mode_requirements.cpp`. + +If the script encounters a flag in `mode_requirements.cpp` that has no entry in +`requirement_defns.json`, it prints a `WARNING:` line to stderr and continues with empty +`text`, `sensor`, and `detail` strings. If the JSON file is missing or malformed the script +exits immediately with a clear `ERROR:` message. + +## Nav-State / Vehicle-Type Metadata + +`mode_nav_state_defns.json` (in the same directory as the script) maps every +`(VEHICLE_TYPE_*, NAVIGATION_STATE_*)` pair to display metadata used when generating +`mode_requirements.md` section headings and controlling per-mode warning behaviour. + +Each entry may contain: + +| Key | Type | Default | Meaning | +|-----|------|---------|---------| +| `label` | string | — | Human-readable mode name (e.g. `"Mission Mode"`) | +| `doc` | string | — | Relative doc path used as a heading hyperlink (e.g. `"../flight_modes_fw/mission.md"`) | +| `warn` | bool | `true` | Set to `false` to suppress warnings for this mode | +| `status` | string | — | Short implementation-status note, used only when `doc` is absent (see below) | + +**Heading generation** (in `mode_requirements.md`): +A mode is only given a full heading + requirement list in the main per-vehicle-type list if it +has a `doc`. Modes with no `doc` are **not** given a bare heading in the main list — instead +they are collected into a trailing `### Modes Without a Dedicated Page` summary for that +vehicle type, rendered as `- **NAV_STATE** — {status}`. Use `status` to explain *why* there's +no dedicated page — e.g. the mode isn't implemented for this vehicle type, or it behaves +identically to another mode already documented, or it's an internal/failsafe state that isn't +user-selectable. If a no-doc mode has no `status` text, the script prints a `WARNING:` to +stderr and falls back to "Not currently documented." + +**Skipping snippet injection:** if an entry has `"warn": false` and no `"doc"` key, the script +skips snippet processing for that mode without printing a warning. Use this for modes that +are not real operational modes (e.g. `TERMINATION`) or that deliberately have no doc page. +(This is orthogonal to `status`: `warn`/`doc` control snippet-injection behaviour, while +`status` controls what's shown in the `mode_requirements.md` summary.) + +If the script encounters a `(vehicle_type, nav_state)` pair that has no entry at all in +`mode_nav_state_defns.json`, it prints a `WARNING:` line to stderr. Add a new entry whenever +a new navigation state is introduced in `mode_requirements.cpp`. + +**Ordering:** the key order of `NAVIGATION_STATE_*` entries within each vehicle-type block in +`mode_nav_state_defns.json` — not the order `setRequirement()` calls appear in +`mode_requirements.cpp` — determines the order modes are rendered in `mode_requirements.md`, +for both the headed list and the trailing "Modes Without a Dedicated Page" summary. The +intended order is low-to-high autonomy (e.g. `MANUAL` → `STAB` → `ACRO` → ... → `OFFBOARD`). +`VEHICLE_TYPE_FIXED_WING` and `VEHICLE_TYPE_ROTARY_WING` are separate JSON objects, so keep +their key order in sync manually when adding or reordering a mode. Any nav_state the parser +finds that has no entry at all in `mode_nav_state_defns.json` is appended after all +JSON-ordered modes (in addition to the existing "no entry" warning). + +The same principle applies one level up: the **top-level** key order of +`mode_nav_state_defns.json` (currently `VEHICLE_TYPE_FIXED_WING` before +`VEHICLE_TYPE_ROTARY_WING`) determines the order the `## Fixed-wing` / `## Multicopter` +sections are rendered in `mode_requirements.md`. This is deliberate — vehicle types are +discovered from `mode_requirements.cpp` into a Python `set`, whose iteration order is +randomized per-process, so the render loops must never iterate that set/dict directly or the +section order will vary between runs for no code reason. Any vehicle type found in the C++ but +absent from the JSON is appended afterwards in sorted order. + +## Parser design + +`parse_requirements()` uses a single-pass token scanner. A single compiled regex (`_TOKEN`) +identifies all meaningful tokens in the `getModeRequirements()` body in left-to-right order: +single-line comments (skipped), `if (vehicle_type == X) {` (push condition), `} else {` (flip +condition), `}` (pop), `{` (push None for non-conditional blocks), and `setRequirement(…)` +calls. A condition stack tracks the innermost active vehicle-type condition; requirements are +assigned to the appropriate vehicle-type set based on whether we are inside an if-branch, an +else-branch, or unconditional code. + +This replaces an earlier two-pass regex approach that was fragile: its non-greedy `[\s\S]*?` +pattern would span across unrelated blocks when a standalone `if` appeared before an `if-else`, +producing silently wrong output for several modes. + +## Tests + +The test suite lives in `tests/` and is a pytest regression suite that guards against +unintended changes to the parser output. It compares the live output of the parser against +golden JSON snapshots: + +``` +tests/ + __init__.py + test_get_mode_requirements.py ← the test module + test_data/ + requirement_defns_golden.json ← expected requirement_defns contents + vehicle_modes_golden.json ← expected parse_requirements() output +``` + +- `test_data/requirement_defns_golden.json` — expected contents of the `requirement_defns` + dict (flag name → text / sensor / detail). +- `test_data/vehicle_modes_golden.json` — expected output of `parse_requirements()` applied + to the checked-in `mode_requirements.cpp`: a per-vehicle-type, per-mode mapping of sorted + requirement flag names. + +`conftest.py` at the package root adds this directory to `sys.path` so pytest can import +`get_mode_requirements` without any install step. + +The suite contains three tests: + +| Test | What it checks | +|---|---| +| `test_requirement_defns_matches_golden` | `requirement_defns` exactly matches the golden snapshot | +| `test_vehicle_modes_matches_golden` | `parse_requirements()` output matches the golden snapshot; prints a per-mode diff on failure | +| `test_all_requirement_flags_are_defined` | Every flag found in `mode_requirements.cpp` has an entry in `requirement_defns` | + +### Running the tests + +From this directory (`get_mode_requirements/`): + +```sh +pytest tests/ -v +``` + +### When to run and update + +**Run the tests** whenever you change: +- the parser logic in `get_mode_requirements.py`, or +- `src/modules/commander/ModeUtil/mode_requirements.cpp`. + +**Update the golden files** after any intentional change to either of the above so that the +snapshots stay in sync with the new expected output: + +```sh +python tests/test_get_mode_requirements.py --update-golden +``` + +Then re-run the tests to confirm they pass, and commit the updated golden files alongside the +parser or C++ changes. diff --git a/docs/scripts/get_mode_requirements/CLAUDE.md b/docs/scripts/get_mode_requirements/CLAUDE.md index f44f3142a5f..43c994c2d36 100644 --- a/docs/scripts/get_mode_requirements/CLAUDE.md +++ b/docs/scripts/get_mode_requirements/CLAUDE.md @@ -1,219 +1 @@ -# get_mode_requirements - -## Purpose - -`get_mode_requirements.py` parses the PX4 flight mode requirements defined in -`src/modules/commander/ModeUtil/mode_requirements.cpp` and generates Markdown documentation. - -It produces two kinds of output under `docs/en/`: - -- `flight_modes/mode_requirements.md` — a consolidated overview table for all vehicle types. -- Per-mode requirement text injected directly into individual flight-mode pages using include markers. - -## Running - -From the repo root: - -```sh -python3 docs/scripts/get_mode_requirements/get_mode_requirements.py -``` - -Or from the `docs/` directory: - -```sh -python3 scripts/get_mode_requirements/get_mode_requirements.py -``` - -## Inline Injection - -The script locates each parent flight-mode doc (e.g. `flight_modes_fw/manual.md`) by scanning -`docs/en/flight_modes/`, `docs/en/flight_modes_fw/`, `docs/en/flight_modes_mc/`, and -`docs/en/advanced_features/` for a VitePress `` directive (or an existing -`AUTO-GENERATED` sentinel block) that references the corresponding snippet name -(`build_snippet_to_parent_map()`). This directory scan is what actually determines where a -mode's requirements get injected — it is **independent** of the `doc` field in -`mode_nav_state_defns.json`, which only controls headings/links in `mode_requirements.md`. A -mode can have a `doc` pointing at a page that isn't scanned (or has no injection marker on it -yet) and still trigger a "not mapped to a doc" warning; fix this by adding an -`` marker pair -(content between them can be empty — the script fills it in) to the actual doc page, and if -that page lives outside the four scanned directories, add its directory to `search_dirs` in -`build_snippet_to_parent_map()`. - -A single doc page can contain multiple injection points for different nav-states (e.g. -`flight_modes/offboard.md` has one per vehicle type; `flight_modes_mc/manual_stabilized.md` -has one for `NAVIGATION_STATE_STAB` and one for `NAVIGATION_STATE_MANUAL`, since those are -distinct nav-states with different requirements that happen to share one doc page). Each -generated block always starts its own `### Mode Requirements` heading, so when adding a second -block to the same page, add distinguishing surrounding text/labels manually to avoid duplicate -headings, then hand-write the marker pair; the script replaces the content and heading between -the markers. - -It replaces that directive with the rendered content, wrapped in sentinel HTML comments: - -```markdown - -### Mode Requirements - -The following requirements must be met to arm in this mode, or to switch to this mode when it is armed. - -- [`mode_req_manual_control`](xxx) - Requires stick input - - -``` - -On subsequent runs the sentinels are detected and the content between them is updated in-place, -so the script is safe to re-run whenever `mode_requirements.cpp` changes. - -**Do not edit the text between the sentinel comments manually** — it will be overwritten on the -next run. Make changes in `requirement_defns.json` or in `mode_requirements.cpp`. - -## Path Calculation - -The script resolves the repository root at runtime using `Path(__file__).resolve()` and -navigating **three** parent directories up: - -``` -docs/scripts/get_mode_requirements/get_mode_requirements.py - -> docs/scripts/get_mode_requirements/ (parent) - -> docs/scripts/ (parent.parent) - -> docs/ (parent.parent.parent) - -> PX4-Autopilot/ (parent.parent.parent.parent) ← repo root -``` - -If this script is ever moved, update the `repo_root` line accordingly. - -## Adding or Changing Requirement Definitions - -`requirement_defns.json` (in the same directory as the script) maps each `mode_req_*` flag -name to a human-readable `text`, an example `sensor`, and an extended `detail` string. Add -new entries here when new requirement flags are introduced in `mode_requirements.cpp`. - -If the script encounters a flag in `mode_requirements.cpp` that has no entry in -`requirement_defns.json`, it prints a `WARNING:` line to stderr and continues with empty -`text`, `sensor`, and `detail` strings. If the JSON file is missing or malformed the script -exits immediately with a clear `ERROR:` message. - -## Nav-State / Vehicle-Type Metadata - -`mode_nav_state_defns.json` (in the same directory as the script) maps every -`(VEHICLE_TYPE_*, NAVIGATION_STATE_*)` pair to display metadata used when generating -`mode_requirements.md` section headings and controlling per-mode warning behaviour. - -Each entry may contain: - -| Key | Type | Default | Meaning | -|-----|------|---------|---------| -| `label` | string | — | Human-readable mode name (e.g. `"Mission Mode"`) | -| `doc` | string | — | Relative doc path used as a heading hyperlink (e.g. `"../flight_modes_fw/mission.md"`) | -| `warn` | bool | `true` | Set to `false` to suppress warnings for this mode | -| `status` | string | — | Short implementation-status note, used only when `doc` is absent (see below) | - -**Heading generation** (in `mode_requirements.md`): -A mode is only given a full heading + requirement list in the main per-vehicle-type list if it -has a `doc`. Modes with no `doc` are **not** given a bare heading in the main list — instead -they are collected into a trailing `### Modes Without a Dedicated Page` summary for that -vehicle type, rendered as `- **NAV_STATE** — {status}`. Use `status` to explain *why* there's -no dedicated page — e.g. the mode isn't implemented for this vehicle type, or it behaves -identically to another mode already documented, or it's an internal/failsafe state that isn't -user-selectable. If a no-doc mode has no `status` text, the script prints a `WARNING:` to -stderr and falls back to "Not currently documented." - -**Skipping snippet injection:** if an entry has `"warn": false` and no `"doc"` key, the script -skips snippet processing for that mode without printing a warning. Use this for modes that -are not real operational modes (e.g. `TERMINATION`) or that deliberately have no doc page. -(This is orthogonal to `status`: `warn`/`doc` control snippet-injection behaviour, while -`status` controls what's shown in the `mode_requirements.md` summary.) - -If the script encounters a `(vehicle_type, nav_state)` pair that has no entry at all in -`mode_nav_state_defns.json`, it prints a `WARNING:` line to stderr. Add a new entry whenever -a new navigation state is introduced in `mode_requirements.cpp`. - -**Ordering:** the key order of `NAVIGATION_STATE_*` entries within each vehicle-type block in -`mode_nav_state_defns.json` — not the order `setRequirement()` calls appear in -`mode_requirements.cpp` — determines the order modes are rendered in `mode_requirements.md`, -for both the headed list and the trailing "Modes Without a Dedicated Page" summary. The -intended order is low-to-high autonomy (e.g. `MANUAL` → `STAB` → `ACRO` → ... → `OFFBOARD`). -`VEHICLE_TYPE_FIXED_WING` and `VEHICLE_TYPE_ROTARY_WING` are separate JSON objects, so keep -their key order in sync manually when adding or reordering a mode. Any nav_state the parser -finds that has no entry at all in `mode_nav_state_defns.json` is appended after all -JSON-ordered modes (in addition to the existing "no entry" warning). - -The same principle applies one level up: the **top-level** key order of -`mode_nav_state_defns.json` (currently `VEHICLE_TYPE_FIXED_WING` before -`VEHICLE_TYPE_ROTARY_WING`) determines the order the `## Fixed-wing` / `## Multicopter` -sections are rendered in `mode_requirements.md`. This is deliberate — vehicle types are -discovered from `mode_requirements.cpp` into a Python `set`, whose iteration order is -randomized per-process, so the render loops must never iterate that set/dict directly or the -section order will vary between runs for no code reason. Any vehicle type found in the C++ but -absent from the JSON is appended afterwards in sorted order. - -## Parser design - -`parse_requirements()` uses a single-pass token scanner. A single compiled regex (`_TOKEN`) -identifies all meaningful tokens in the `getModeRequirements()` body in left-to-right order: -single-line comments (skipped), `if (vehicle_type == X) {` (push condition), `} else {` (flip -condition), `}` (pop), `{` (push None for non-conditional blocks), and `setRequirement(…)` -calls. A condition stack tracks the innermost active vehicle-type condition; requirements are -assigned to the appropriate vehicle-type set based on whether we are inside an if-branch, an -else-branch, or unconditional code. - -This replaces an earlier two-pass regex approach that was fragile: its non-greedy `[\s\S]*?` -pattern would span across unrelated blocks when a standalone `if` appeared before an `if-else`, -producing silently wrong output for several modes. - -## Tests - -The test suite lives in `tests/` and is a pytest regression suite that guards against -unintended changes to the parser output. It compares the live output of the parser against -golden JSON snapshots: - -``` -tests/ - __init__.py - test_get_mode_requirements.py ← the test module - test_data/ - requirement_defns_golden.json ← expected requirement_defns contents - vehicle_modes_golden.json ← expected parse_requirements() output -``` - -- `test_data/requirement_defns_golden.json` — expected contents of the `requirement_defns` - dict (flag name → text / sensor / detail). -- `test_data/vehicle_modes_golden.json` — expected output of `parse_requirements()` applied - to the checked-in `mode_requirements.cpp`: a per-vehicle-type, per-mode mapping of sorted - requirement flag names. - -`conftest.py` at the package root adds this directory to `sys.path` so pytest can import -`get_mode_requirements` without any install step. - -The suite contains three tests: - -| Test | What it checks | -|---|---| -| `test_requirement_defns_matches_golden` | `requirement_defns` exactly matches the golden snapshot | -| `test_vehicle_modes_matches_golden` | `parse_requirements()` output matches the golden snapshot; prints a per-mode diff on failure | -| `test_all_requirement_flags_are_defined` | Every flag found in `mode_requirements.cpp` has an entry in `requirement_defns` | - -### Running the tests - -From this directory (`get_mode_requirements/`): - -```sh -pytest tests/ -v -``` - -### When to run and update - -**Run the tests** whenever you change: -- the parser logic in `get_mode_requirements.py`, or -- `src/modules/commander/ModeUtil/mode_requirements.cpp`. - -**Update the golden files** after any intentional change to either of the above so that the -snapshots stay in sync with the new expected output: - -```sh -python tests/test_get_mode_requirements.py --update-golden -``` - -Then re-run the tests to confirm they pass, and commit the updated golden files alongside the -parser or C++ changes. +@AGENTS.md