From dd1897d91605dceed7c955985477eac60fe91c08 Mon Sep 17 00:00:00 2001 From: eding Date: Mon, 14 Sep 2026 23:07:25 +0200 Subject: [PATCH 1/2] docs: require PR handoff --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3c39c74 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,10 @@ +# MaidnCLI Delivery Procedure + +## Handoff + +- Do not leave completed changes only in a local worktree or branch. +- Run `git diff --check` and the applicable Go checks before handoff. +- 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. +- Never commit generated workspaces, `.password`, SOPS material, kubeconfigs, Terraform state, or recovery material. From 523148a4be966bd37aaa0100ea76189c207094ab Mon Sep 17 00:00:00 2001 From: eding Date: Mon, 14 Sep 2026 23:28:00 +0200 Subject: [PATCH 2/2] docs: standardize review handoff --- AGENTS.md | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3c39c74..090c4ff 100644 --- a/AGENTS.md +++ b/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. -- Run `git diff --check` and the applicable Go checks before handoff. -- Push each safe, scoped change on its own branch. +- 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. -- Return the PR URL. If Forgejo API access prevents PR creation, return the compare URL and state the exact API failure. -- Never commit generated workspaces, `.password`, SOPS material, kubeconfigs, Terraform state, or recovery material. +- 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: +Branch: +Purpose: +Checks: - PASS|FAIL|BLOCKED +Risk: +Merge: +``` + +## 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.