diff --git a/AGENTS.md b/AGENTS.md index 7c581aa..f2cda7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,6 @@ setting it up in an agent VM and where it stands on readiness for agents. ## Development -How to check your own work here. Check each change with these commands before you call it done, -fix what fails, and report what you ran and what it returned. - - Two Gradle subprojects: `smoothness-weblib`, the library (Java classes, JSP tags, and the JavaScript and CSS under `src/main/resources/META-INF`), and `smoothness-demo`, a web app that shows it off and is how you see a library change working. @@ -25,8 +22,7 @@ fix what fails, and report what you ran and what it returned. converters use the JVM's default time zone and locale. - The unit tests are characterization tests: they record what the code does now, quirks included (such as `isSameMonth` ignoring the year). When you change behavior on purpose, change - the test that records it and say so in the pull request. Add or update tests with each change, - check that a new test fails without your fix, and never skip or weaken a test to make it pass. + the test that records it and say so in the pull request. Test servlet code with `FakeRequest` (parameters and paths only), filters with `FakeHttp` (request, response, and chain), and settings with `TestSettings.cache`, rather than a mocking library. @@ -54,7 +50,7 @@ fix what fails, and report what you ran and what it returned. created (the demo's movies and the settings). `docker compose -f build.yaml down -v` deletes it; the next `up` rebuilds it. Each clone or worktree gets its own containers, named after its directory, but needs its own ports in a `.env` (see the README); a stack uses about 4 GB of - memory. Never use production data. + memory. - Accounts (Keycloak test realm, password `password`): `jdoe` and `tbrown` are admins (`smoothness-demo-admin`); `jadams` and `jsmith` are users. A login made before Keycloak is healthy gets a session without its roles: log in again. @@ -77,57 +73,173 @@ fix what fails, and report what you ran and what it returned. new version's files. - Schema and settings changes go in `container/oracle/initdb.d`; there are no migrations, so describe the SQL that existing databases need in the pull request. -- Never commit secrets. Local port settings go in `.env`, which git ignores. +- Local port settings go in `.env`, which git ignores. + + + +## Shared rules + +These rules are the same in every project that uses them. Where this file's other sections say +otherwise, follow those. + +### Checking your work + +- Check each change with the Development section's commands before you call it done, fix what + fails, and report what you ran and what it returned. +- Verify every change with checks appropriate to its behavior and regression risk. Add or update + tests where that risk warrants them; meaningful existing coverage can suffice. For bug fixes, + show the regression test fails without the fix and passes with it when practical; explain when + this cannot be shown. For documentation or formatting, check links, examples, or formatting + as applicable. Never skip or weaken a check merely to make it pass. +- For code with thin tests, use characterization tests where they help establish a baseline: + they record existing behavior, not necessarily correct behavior. Separate them into a test-only + merge request when risk or review needs warrant it; otherwise include them with the change. +- Never use production data, and never commit secrets. -## Commit identity +### Task authorization + +- Use the request and authorization already given in the session; do not ask again for an + authorized action. “Look around and suggest improvements” means investigate, run local + checks, and report; it does not authorize implementing or publishing the suggestions. +- An implementation request such as “Fix this bug” authorizes the local changes and verification + needed to finish it. Complete them; ask before a material expansion of scope. +- Commit and push only when asked. “Create a merge request for issue #14” also authorizes + implementation, verification, commits, pushing the branch, and opening the merge request. + A local implementation request alone does not. A request to address review on that merge + request authorizes the necessary follow-up commits and pushes. +- A requested review authorizes checks and posting findings as comments. Commit and push review + fixes only when asked; follow the review conventions below. +- Releases, deployments, production data changes, and settings changes in external systems need + authorization for the action and target environment. A request to implement a change or open + a merge request alone does not give it. Follow the project's release, issue-filing, and access + rules; never approve, merge, or enable auto-merge. +- Ask only when a consequential ambiguity remains; continue independent work within the + authorized scope while waiting. + +### Commit identity Commits written by an agent must say so. Before committing, check that the repository-local -identity (never `--global`) is that of the GitHub App bot you push with, so GitHub links the -commits to it and squash commits show the same name. Never commit under a person's name or -email. Name the agent and model in a trailer: keep the one your tool adds (such as +identity (never `--global`) is the bot's whose token you push with, so the Git host links the +commits to it and squash commits show the same name: + +```bash +git config user.name "" # e.g. " agent VM[bot]" +git config user.email "" +``` + +On GitLab, `glab api user` shows the bot's `name` and `username`, and the address is +`@noreply.` (for example `project_…_bot_…@noreply.code.jlab.org`). Never commit +under a person's name or email. Name the agent and model in a trailer on every agent-written +commit, including follow-up and reviewer commits: keep the one your tool adds (such as `Co-Authored-By`), or else add `Assisted-by: :`. -## Commits +### Commits - Imperative summary line, then a body explaining what changed and why. -- Squash merges use the commit messages: write the first one for `main`. +- Trailers come last, in one paragraph: the release trailers this file asks for, if any (such as + `Changelog:`), then tool-required ones, with no blank line between them. Git reads trailers + only from the last paragraph; check with + `git log -1 --format=%B | git interpret-trailers --parse`. +- The squash commit message template uses the first commit's message: write it for `main`, and + put release trailers on it only. Later commits, including a reviewer's, retain agent/model + attribution trailers but omit release trailers. Keep the first message current for the whole + change, preserving its attribution and adding any distinct agent/model attribution from later + commits so the squash credits them too. - Commit and push only when asked. -## Branches and pull requests +### Branches and merge requests - Start each task on a new branch from an up-to-date `main`; target `main`. Work only in your own clone or worktree. -- Label every pull request `source::ai`, and make the person who reviews it both reviewer and - assignee (ask for their username if you don't know it). In gh 2.46, `gh pr edit` fails; add - labels and retarget with `gh api` (see the coding-agents Git workflow guide's tool notes). -- You cannot add items to the JeffersonLab organization's project: when you report back, list - the pull requests and issues you opened, so the person can add them to the period's project. -- Never change `VERSION` unless asked: a change to it on `main` releases the project (tag, GitHub - release with the demo war, the weblib on Maven Central, the docs, the demo Docker image, and a - deploy to JLab's test server). When asked, open a pull request that changes only `VERSION`, - and write any upgrade steps in its description for the maintainer to add to the release. -- A person reviews and merges, and merged branches are deleted; never merge, approve, or enable - auto-merge yourself. -- Before pushing to a pull request's branch, check that it is still open: commits pushed after it - merged never reach `main`, so put them in a new pull request. -- To build on a pull request still in review, branch from its branch and target that branch, +- Label every merge request `source::ai`, and make the person who reviews it both reviewer and + assignee (ask for their username if you don't know it). +- Delete the source branch on merge. A person reviews and merges; never merge, approve, or + enable auto-merge yourself. +- Before pushing to a merge request's branch, check that it is still open: commits pushed after + it merged never reach `main`, so put them in a new merge request. +- To build on a merge request still in review, branch from its branch and target that branch, saying so in the description. Once the first merges, check that yours now targets `main`, and - retarget it if not. -- Describe what changed, any deployment steps, and the checks you ran, including what you could - not run. Add a short Decisions part when the person questioned or changed something, or when - alternatives were dropped. -- After pushing, wait for the pull request's checks to finish before reporting it ready (`build` - and `integration` from CI, and CodeQL; `integration` takes about 5 minutes); - `gh pr checks --watch` waits. Read failed jobs' logs and fix the - cause; never skip or weaken a check to pass it. Report how they ended, and say if one failed - for a reason outside your change. + retarget it if not: GitHub retargets it only if the merged branch was deleted. +- Describe what changed, any deployment steps, and the checks you ran. Add a short Decisions + part: what the person questioned or changed during the session, which alternatives were + dropped and why, and any second opinion that changed something. +- After pushing, wait for the merge request's pipeline to finish before reporting it ready. Read + failed jobs' logs and fix the cause; never skip or weaken a check to pass it. Report how it + ended, with its link, and say if it failed for a reason outside your change. On GitLab, + `glab mr view -F json | jq '.head_pipeline | {sha, status, web_url}'` shows it; plain + `glab ci status` can miss merge request pipelines, and `--live` waits only in a terminal. - Name the issue a change is for in the commit body: `Fixes #`, or `Part of #` if some of it stays open. Work you were asked to do needs no issue. +- For another GitLab project's issue or merge request, prefer `project#123` or + `project!456` with no space, when it resolves correctly from the current context. Check + the rendered link's destination before publishing. Otherwise use the full namespace path + or full URL; GitLab can display the URL as a reference. An explicit Markdown link can + use a concise label. `project #123` and + `project !456` link the bare number to the current project. Apply this to descriptions, + comments, commit messages, and documentation. + +### Issues + - For something outside your task (another project, code another agent is working on, or a change that needs a decision), don't fix it in passing: offer to open an issue, labeled `source::ai` and assigned to the person you work with, with what you found, the evidence, and a suggested fix. -- When asked to address a review, reply in each thread with what you changed, and push new - commits rather than rewriting ones already reviewed; the reviewer resolves the threads. +- File issues as the bot with `source::ai`, and end their descriptions (including planning + issues) with a plain-text `Prepared-by: :` footer, such as + `Prepared-by: OpenAI Codex:`, + `Prepared-by: Anthropic Claude Code:`, or + `Prepared-by: Google Gemini:`. Use the specific model identifier + when known; otherwise use the known model family (for example `GPT-6`), omitting unknown + variant or version details. Use `unavailable` only when neither is known; never guess. + Preserve existing footers; + for substantive analysis, proposed-change, or acceptance-criteria updates, append your own + if that vendor, agent, and model are not already credited. Routine metadata or formatting + edits need no new footer. +- When asked to plan work for other agents: check claims before filing, list draft issues before + filing them, make each one self-contained with "Done when" and what not to do, say which can + start now and which are blocked or share files, and ask before filing anything + security-sensitive (file it confidential). + +### Review + +- When asked to address a review, reply in each thread with what you changed, and push content + fixes as new commits; the reviewer resolves the threads. The author may reword only the first + message when its description, release metadata, or attribution needs updating. Coordinate + with anyone working on the branch, save the old tip, and keep the base, patches, and commit + order unchanged. Rewording changes descendant IDs too: check `git range-diff` between the old + and new series for only the intended message change, and `git diff HEAD` for no tree + change. Push with `--force-with-lease=refs/heads/:`; stop if the lease + fails. Report the old/new tips and message changes so the reviewer can compare patches. +- When asked to review a merge request, leave comments by default without asking which mode to + use. Commit and push fixes only when asked; coordinate with the author before pushing if they + are still working on the branch. Add one commit per recommendation on top of the author's + (never rewrite theirs), retaining your agent/model attribution but omitting release trailers + on follow-up commits. Then post one comment listing each commit, what you tested, that the + author must pull, and any first-message update needed for the whole change or squash + attribution. Never approve, merge, or resolve threads. - When the person corrects you on something any agent here should know, propose adding it to - this file, or better a check that catches it. Keep one developer's preferences out of it. + this file's project rules, or better a check that catches it. Keep one developer's preferences + out of it. + + + +## Project rules + +### GitHub + +This project is on GitHub: where the shared rules say merge request, read pull request, and for +its pipeline, its checks: `build` and `integration` from CI, and CodeQL (`integration` takes +about 5 minutes; `gh pr checks --watch` waits). In gh 2.46, `gh pr edit` fails; add +labels and retarget with `gh api` (see the coding-agents Git workflow guide's tool notes). + +### Releases + +Never change `VERSION` unless asked: a change to it on `main` releases the project (tag, GitHub +release with the demo war, the weblib on Maven Central, the docs, the demo Docker image, and a +deploy to JLab's test server). When asked, open a pull request that changes only `VERSION`, and +write any upgrade steps in its description for the maintainer to add to the release. + +### GitHub organization project + +You cannot add items to the project: when you report back, list the pull requests and issues you +opened, so the person can add them to the period's project.