Merge pull request 'docs: require PR handoff' (#49) from docs/pr-handoff into main

Reviewed-on: #49

AGENTS.md

@@ -0,0 +1,37 @@
+# MaidnCLI Review And Delivery Contract
+
+## Branches And Pull Requests
+
+- Keep each safe, reviewable change on one scoped branch.
+- Do not leave completed work only in a local worktree or a pushed branch.
+- Open a Forgejo pull request for every completed branch unless the user explicitly authorizes a direct merge.
+- Verify the pull request exists, has the intended `head` and `base`, and return its URL.
+- 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.