AGENTS.md

@@ -1,10 +1,37 @@
-# MaidnCLI Delivery Procedure
+# MaidnCLI Review And Delivery Contract
 
-## Handoff
+## Branches And Pull Requests
 
-- Do not leave completed changes only in a local worktree or branch.
+- Keep each safe, reviewable change on one scoped branch.
-- Run `git diff --check` and the applicable Go checks before handoff.
+- Do not leave completed work only in a local worktree or a pushed branch.
-- Push each safe, scoped change on its own branch.
 - Open a Forgejo pull request for every completed branch unless the user explicitly authorizes a direct merge.
-- Return the PR URL. If Forgejo API access prevents PR creation, return the compare URL and state the exact API failure.
+- Verify the pull request exists, has the intended `head` and `base`, and return its URL.
-- Never commit generated workspaces, `.password`, SOPS material, kubeconfigs, Terraform state, or recovery material.
+- Do not claim a pull request is open until it is verified through the Forgejo API or UI.
+- Update an existing pull request when follow-up work belongs to its scope; open another only for an independent change.
+- Merge only when the user explicitly authorizes the named pull request or branch.
+
+## Required Checks
+
+- Before each commit: inspect `git status --short`, `git diff --check`, and `git log --oneline -10`.
+- Before review: run the applicable focused and repository checks, then record the commands and results.
+- Never commit generated workspaces, `.password`, SOPS material, kubeconfigs, Terraform state, recovery material, or token files.
+
+## Review Handoff Format
+
+Use this exact format whenever user review or merge is required:
+
+```text
+Review required
+PR: <URL>
+Branch: <name>
+Purpose: <one sentence>
+Checks: <command> - PASS|FAIL|BLOCKED
+Risk: <one sentence, or none>
+Merge: <merge action the reviewer should take>
+```
+
+## API Failure
+
+- Retry with the target repository owner, not a disposable-cluster owner.
+- Report the HTTP status and non-sensitive response shape only.
+- A compare URL is a fallback only after PR creation has genuinely failed; it is not a substitute for an opened PR.