loopx AGENTS.md

Agent Instructions

Commit And PR Hygiene

Worktree And PR Gate

For any tracked repository change beyond a trivial typo fix, create or use a dedicated clean git worktree on a codex/ branch. Use latest origin/main unless the user explicitly names an integration or release branch; in that case, fetch that branch and use its latest remote head as both the worktree baseline and pull-request base. Before pushing, verify the merge base and PR base so unrelated main history cannot leak into a stacked integration PR. Do not implement changes directly in a dirty primary worktree, even when the task starts by inspecting that dirty tree.

When a dirty worktree contains potentially valuable changes, first classify it read-only, then copy or reapply the valuable subset into the dedicated clean worktree and open a PR from that branch. Reset or clean the original dirty worktree only after the valuable subset has been merged or explicitly judged obsolete. Leave unrelated untracked local artifacts alone.

Every tracked repository change must be pushed on a branch and reviewed through a pull request before it reaches main. Do not push broad mixed commits or direct commits to main.

DCO Sign-Off

Every commit in a pull-request branch must include a Signed-off-by: Your Name <[email protected]> trailer, or the DCO check will reject the PR. Always commit with git commit -s. If a commit is already missing the trailer, amend it with git commit --amend -s (or an interactive rebase for multiple commits) before pushing. See CONTRIBUTING.md for the full DCO policy.

Only skip this worktree/PR gate when the user explicitly says the change is local-only and must not be proposed for the repository.

For non-trivial repository changes, especially anything that touches benchmark adapters, smoke tests, public docs, or commit/push workflows, use the git-split-commit-pr workflow before staging:

1. Establish ground truth with git status --short --branch, git diff --stat, git diff --name-only, and git ls-files --others --exclude-standard.
2. Classify every changed path before staging:
   • core product code;
   • core documentation;
   • durable validation smoke;
   • local/private state;
   • low-value or obsolete artifact.
3. Scan candidate paths for credentials, private state, local absolute paths, raw benchmark logs, trajectories, verifier output, and internal links.
4. Stage by explicit pathspecs only. Do not use git add ..
5. Split commits by reviewer logic:
   • runtime/API behavior;
   • public docs and protocol notes;
   • focused validation or cleanup.
6. Push a branch and open a PR for reviewable batches.