From 1b2cfbafe03be5cd2e62743eff9951dc22411cc7 Mon Sep 17 00:00:00 2001 From: atheate Date: Fri, 29 May 2026 12:06:28 +0200 Subject: [PATCH 1/3] [Update] enforce mandatory PR workflow on extension commands Adds Phase PR (commit + push + gh pr create) to both /implement-extensions and /implement-extensions-batch as a mandatory final phase, and codifies the rule in CLAUDE.md as 'Branch & PR workflow (MANDATORY)'. Every branch must reach an open PR against development; direct pushes to development or master are forbidden. --- .../commands/implement-extensions-batch.md | 74 +++++++++++++++---- .claude/commands/implement-extensions.md | 51 ++++++++++++- CLAUDE.md | 23 +++++- 3 files changed, 129 insertions(+), 19 deletions(-) diff --git a/.claude/commands/implement-extensions-batch.md b/.claude/commands/implement-extensions-batch.md index c1d2909d..d872856c 100644 --- a/.claude/commands/implement-extensions-batch.md +++ b/.claude/commands/implement-extensions-batch.md @@ -327,11 +327,61 @@ step-11 logic from `/implement-extensions`: 6. Push via `gh issue edit --body-file `. 7. Re-fetch + diff to verify only the Checklist section changed. -### 14. Final summary +### 14. Phase PR — Commit, push, open PR (MANDATORY) + +This phase is non-skippable. Every batch run ends with a pushed branch and an open PR against `development`. See the user-memory rule `feedback_pr_mandatory.md` and the CLAUDE.md "Branch & PR workflow (MANDATORY)" section. + +1. **Stage in-scope files EXPLICITLY** — NEVER `git add -A` / `git add .`. Stage only: + - the N production files `SysML2.NET/Extend/Extensions.cs`, + - the N test fixtures `SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs`, + - any sibling fixtures the regression sweep (step 11) touched. + + ```bash + git add SysML2.NET/Extend/Extensions.cs SysML2.NET/Extend/Extensions.cs … \ + SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs … \ + + ``` + + `.team-notes/` is gitignored so it stays local automatically. + + **If the working tree contains files outside the in-scope list** (e.g. instruction-file updates surfaced mid-run, scratch files), do NOT stage them in this commit. Either split them into a separate follow-up commit on the same branch (recommended) or surface to the user and pause. + +2. **Commit** with the canonical batch message — single line, no body, no trailers, no `--no-verify`: + + ```bash + git commit -m "Fix # # # …" + ``` + + The numbers are exactly the GitHub issue numbers handled by this batch, in the original `$ARGUMENTS` order (or, if the user expressed a preferred order in the invocation prompt, that order). + +3. **Push** the branch to `origin`: + + ```bash + git push -u origin + ``` + + NEVER `--force`. NEVER `--force-with-lease`. If the push is rejected because the branch diverged from origin (unlikely for a fresh batch branch, but possible if the user pushed manually mid-run), surface the conflict and stop. + +4. **Open the PR** against `development`: + + ```bash + gh pr create --base development --head \ + --title "Fix # # # …" \ + --body-file + ``` + + The PR body is the per-file table + branch-wide totals from step 15, without the pre-filled-commit-message block (the commit has already been made). NEVER use `--draft` unless the user explicitly asked. NEVER use `--base master`. + +5. **Capture the PR URL** from `gh pr create`'s stdout and pass it to step 15. + +If the current branch is `development` or `master` at this point (defensive check; should never happen for a batch run), ABORT the workflow — feature work belongs on a feature branch. Surface to the user and do not push. + +### 15. Final summary Print to the user: -- **Branch**: name + base ref + how to delete-if-aborting. +- **Branch**: name + base ref. +- **PR**: `` (captured from step 14.5). - **Per-file table**: | File | Stubs impl. | Targeted tests | Reg. sweep impact | Reviewer | Issue | @@ -340,28 +390,20 @@ Print to the user: | `Extensions.cs` | … | … | … | … | … | - **Branch-wide totals**: - - Files modified (sum of production + tests + notes). + - Files modified (sum of production + tests + sibling fixtures touched). `.team-notes/` are gitignored and not committed. - Full solution test count (e.g. `1082/1082`). - Unresolved reviewer findings (if any). - Spec-text-only methods flagged separately (grounded in spec prose, not OCL). - Out-of-scope blockers surfaced (e.g. "VerifyComputeX in TestFixture is still stub-blocked on `` — consider a follow-up issue"). -- **Pre-filled commit message** (MANDATORY — append at the very end of the - final-summary message in a fenced code block, ready to copy): +- **Commit message used** (informational — the commit is already on the branch): ``` Fix # # # … ``` - Where the numbers are exactly the GitHub issue numbers handled by this - batch, in the original `$ARGUMENTS` order (or, if the user expressed a - preferred order in the invocation prompt, that order). Nothing else — - no body paragraphs, no per-file bullet list, no `Co-Authored-By` trailer, - no "🤖 Generated with …" footer. The single line is the entire message. - -- **Reminder**: nothing is auto-committed. User reviews `git diff`, decides - whether to commit / push / open PR. +- **PR is the review surface.** The user reviews the PR on GitHub — do not ask them to review `git diff` locally. ## Failure handling @@ -380,6 +422,10 @@ Print to the user: | Reviewer NEEDS FIX for one or more files | Step 12 | Re-dispatch THE implementer or THE tester with a focused brief naming the broken file(s); other files' results still reported. | | Implementer's context runs out mid-batch | Any IT/V step | Re-dispatch THE implementer with a focused brief covering only the unfinished file(s). Partial progress on disk is preserved. | | Batch partially fails after branch + assignment | Any step ≥ 6 | Keep the branch; surface in final summary; user decides whether to retry via `/implement-extensions` for the still-broken single file or revert. | +| `git push` rejected (branch diverged from origin) | Phase PR (step 14.3) | Abort the push, surface to user, do NOT force-push. | +| `gh pr create` fails (no GitHub auth, repo write permission missing) | Phase PR (step 14.4) | Surface the gh error, leave the branch pushed, advise the user to open the PR manually. | +| Working tree contains files outside the in-scope list at Phase PR | Phase PR (step 14.1) | Refuse to stage them in the `Fix #…` commit. Either split into a separate follow-up commit on the same branch or surface to the user. | +| Current branch is `development` or `master` at Phase PR | Phase PR (defensive) | ABORT the workflow — feature work belongs on a feature branch. Surface to the user. | ## Parallelism caps (orchestrator self-enforced) @@ -407,7 +453,7 @@ context per role. mistranslation. - The branch and the assignments persist even on partial failure. Be explicit in the final summary about which files succeeded vs which need follow-up. -- Do NOT auto-commit. The user reviews `git diff` and commits manually. +- **Phase PR is MANDATORY** (step 14). Commit + push + open PR at the end of every batch run. The PR is the user's review surface; do NOT ask the user to review `git diff` and commit manually. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". - If the user supplies a single file, route them to `/implement-extensions` with the same filename rather than creating a degenerate 1-file "batch" branch. diff --git a/.claude/commands/implement-extensions.md b/.claude/commands/implement-extensions.md index 5aa0aa10..73fa64b0 100644 --- a/.claude/commands/implement-extensions.md +++ b/.claude/commands/implement-extensions.md @@ -380,8 +380,8 @@ Report to the user: knows the implementation is grounded in spec prose rather than OCL. - **Issue checklist sync**: `` — `` newly ticked, `` newly added, `/` total (filled in after step 11). -- **Pre-filled commit message** (MANDATORY — append at the very end of the - final-summary message in a fenced code block, ready to copy): +- **PR URL**: `` (captured in step 12 / Phase PR). +- **Commit message used** (informational — the commit is already on the branch): ``` Fix # @@ -391,7 +391,7 @@ Report to the user: no body paragraphs, no per-method bullet list, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer. The single line is the entire message. -Do NOT auto-commit. The user reviews and commits. +The PR is the user's review surface — do NOT ask them to review `git diff` and commit manually. See CLAUDE.md "Branch & PR workflow (MANDATORY)" and `feedback_pr_mandatory.md`. ### 11. Sync GitHub issue checklist @@ -452,6 +452,50 @@ unresolved findings are separately surfaced in the final-summary report. The newly ticked items, count of newly added items, and the resulting `/` ratio. +### 12. Phase PR — Commit, push, open PR (MANDATORY when on a non-development branch) + +This phase is non-skippable. Every `/implement-extensions` run ends with a pushed branch and an open PR against `development`. See the user-memory rule `feedback_pr_mandatory.md` and the CLAUDE.md "Branch & PR workflow (MANDATORY)" section. + +**Defensive guard**: check the current branch first. + +```bash +git branch --show-current +``` + +If it is `development` or `master`, ABORT — surface a hard refusal to the user. Feature work belongs on a feature branch first; the user should `git switch -c ` then re-invoke. Do NOT push. + +Otherwise: + +1. **Stage in-scope files EXPLICITLY** — NEVER `git add -A` / `git add .`: + ```bash + git add SysML2.NET/Extend/Extensions.cs \ + SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs \ + + ``` + `.team-notes/` is gitignored so it stays local automatically. + +2. **Commit** with the canonical single-issue message: + ```bash + git commit -m "Fix #" + ``` + Single line, no body, no trailers, no `--no-verify`. + +3. **Push** the branch: + ```bash + git push -u origin + ``` + NEVER `--force` / `--force-with-lease`. If push is rejected because the branch diverged, surface the conflict and stop. + +4. **Open PR** against `development`: + ```bash + gh pr create --base development --head \ + --title "Fix #" \ + --body-file + ``` + PR body is the per-method test result + reviewer verdict from step 10. NEVER `--base master`. + +5. **Capture the PR URL** and feed it back into the step-10 final-summary line. + ## Notes for the orchestrator (you, the main agent) - Pick the model per role using the complexity-grading rubric in step 3.5. @@ -482,6 +526,7 @@ unresolved findings are separately surfaced in the final-summary report. The implementation state of the file; unresolved findings are separately surfaced in the final-summary report. The `gh issue edit` push must touch ONLY the `### Checklist` section — verify with a re-fetch + diff before reporting "done". +- **Phase PR (step 12) is MANDATORY.** Commit + push + open PR at the end of every run. The PR is the user's review surface; do NOT ask the user to review `git diff` and commit manually. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". Refuse to push if the current branch is `development` or `master`. - **Plan mode is handled by Gate 0 at the top of this file** — the orchestrator writes the proposed-execution plan to the plan file, calls `ExitPlanMode`, and proceeds on approval. The orchestrator never spawns sub-agents while plan mode is active, so the previous "degraded mode" workaround is no longer needed and has been removed. - **Gate R-A (step 5.5) is mandatory every run.** It is the only structural checkpoint between the researcher returning `spec ready` and the implementer + tester being spawned. Do not skip it even when the researcher reports zero ambiguities — the user explicitly asked for an unconditional gate so they can review per-method derivations before code is written. - **Tool-level prompts (`Bash(...)`, `Edit(...)`, `Write(...)`, `Agent(...)`) still surface per the user's `settings.json`.** Gate 0 and Gate R-A govern STRUCTURAL approval only. The user has explicitly chosen to keep handling tool-level prompts manually rather than auto-allowing them via permission rules or hooks. diff --git a/CLAUDE.md b/CLAUDE.md index cd7a925a..bf632861 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -142,12 +142,31 @@ Auto-generated DTOs use structured namespaces reflecting the KerML/SysML package ## Key Conventions -- Commit messages use prefix tags: `[Add]`, `[Update]`, `[Remove]`, `[Fix]` -- Main branch: `master`. Development branch: `development` +- Commit messages use prefix tags: `[Add]`, `[Update]`, `[Remove]`, `[Fix]` — except for issue-fixing commits produced by `/implement-extensions` and `/implement-extensions-batch`, which use the canonical short form `Fix #` (single issue) or `Fix # # …` (batch) so GitHub auto-closes the issues on merge. +- Main branch: `master`. Development branch: `development`. **All feature work targets `development`** via PR; `master` is downstream only. - CI: GitHub Actions (`CodeQuality.yml`) — builds, tests, and runs SonarQube analysis - License: Apache 2.0 (code), LGPL v3.0 (metamodel files) - To add a new metaclass: update the UML XMI source files, then run the code generators — do not manually create AutoGen files +## Branch & PR workflow (MANDATORY) + +Every branch must be pushed and have an open PR against `development` before any task is reported "done". The PR is the user's review surface — the agent does NOT ask the user to review `git diff` manually before committing. Direct pushes to `development` or `master` are forbidden. + +Operationally, at the end of any task that creates a branch (most commonly `/implement-extensions` and `/implement-extensions-batch`): + +1. **Stage in-scope files explicitly** — `git add …`. NEVER `git add -A` or `git add .` (sensitive files / drift can leak). +2. **Commit** with the canonical short message: `Fix #` for single-issue runs, `Fix # # …` for batches. Single line. No body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer, no `--no-verify`. +3. **Push**: `git push -u origin `. NEVER `--force`, NEVER `--force-with-lease`. +4. **Open PR**: `gh pr create --base development --head --title "Fix #…" --body-file `. Capture the PR URL and surface it in the final summary. +5. **If the current branch is `development` or `master`**: REFUSE the workflow. Surface to the user — feature work must live on a feature branch first. + +Failure modes: +- `git push` rejected (branch diverged from origin) → abort, surface, do NOT force-push. +- `gh pr create` fails (no auth, no write permission) → leave the branch pushed, advise the user to open the PR manually. +- Mid-task non-payload edits (e.g. instruction-file updates surfaced during a batch) → split into separate commits on the same branch so the `Fix #…` commit carries only the issue-resolving payload. + +This policy reverses any older slash-command snippet that says "Do NOT auto-commit; the user reviews `git diff` and commits manually" — those snippets have been superseded by Phase PR. + ## Quality rules - Prefer comparing 'Count' to 0 rather than using 'Any()', both for clarity and for performance From f51045609f791d056ab304c62be67840f1b065cf Mon Sep 17 00:00:00 2001 From: atheate Date: Fri, 29 May 2026 12:17:40 +0200 Subject: [PATCH 2/3] Mandatory no auto-commits --- .../commands/implement-extensions-batch.md | 112 ++++++++---------- .claude/commands/implement-extensions.md | 61 +++++----- CLAUDE.md | 21 ++-- 3 files changed, 95 insertions(+), 99 deletions(-) diff --git a/.claude/commands/implement-extensions-batch.md b/.claude/commands/implement-extensions-batch.md index d872856c..5eb5faae 100644 --- a/.claude/commands/implement-extensions-batch.md +++ b/.claude/commands/implement-extensions-batch.md @@ -327,61 +327,13 @@ step-11 logic from `/implement-extensions`: 6. Push via `gh issue edit --body-file `. 7. Re-fetch + diff to verify only the Checklist section changed. -### 14. Phase PR — Commit, push, open PR (MANDATORY) +### 14. Final summary + commit-ready handoff -This phase is non-skippable. Every batch run ends with a pushed branch and an open PR against `development`. See the user-memory rule `feedback_pr_mandatory.md` and the CLAUDE.md "Branch & PR workflow (MANDATORY)" section. - -1. **Stage in-scope files EXPLICITLY** — NEVER `git add -A` / `git add .`. Stage only: - - the N production files `SysML2.NET/Extend/Extensions.cs`, - - the N test fixtures `SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs`, - - any sibling fixtures the regression sweep (step 11) touched. - - ```bash - git add SysML2.NET/Extend/Extensions.cs SysML2.NET/Extend/Extensions.cs … \ - SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs … \ - - ``` - - `.team-notes/` is gitignored so it stays local automatically. - - **If the working tree contains files outside the in-scope list** (e.g. instruction-file updates surfaced mid-run, scratch files), do NOT stage them in this commit. Either split them into a separate follow-up commit on the same branch (recommended) or surface to the user and pause. - -2. **Commit** with the canonical batch message — single line, no body, no trailers, no `--no-verify`: - - ```bash - git commit -m "Fix # # # …" - ``` - - The numbers are exactly the GitHub issue numbers handled by this batch, in the original `$ARGUMENTS` order (or, if the user expressed a preferred order in the invocation prompt, that order). - -3. **Push** the branch to `origin`: - - ```bash - git push -u origin - ``` - - NEVER `--force`. NEVER `--force-with-lease`. If the push is rejected because the branch diverged from origin (unlikely for a fresh batch branch, but possible if the user pushed manually mid-run), surface the conflict and stop. - -4. **Open the PR** against `development`: - - ```bash - gh pr create --base development --head \ - --title "Fix # # # …" \ - --body-file - ``` - - The PR body is the per-file table + branch-wide totals from step 15, without the pre-filled-commit-message block (the commit has already been made). NEVER use `--draft` unless the user explicitly asked. NEVER use `--base master`. - -5. **Capture the PR URL** from `gh pr create`'s stdout and pass it to step 15. - -If the current branch is `development` or `master` at this point (defensive check; should never happen for a batch run), ABORT the workflow — feature work belongs on a feature branch. Surface to the user and do not push. - -### 15. Final summary +After Phase IS completes, the orchestrator stops and surfaces a final summary. **The orchestrator does NOT run `git add` or `git commit`** — the user is the reviewer of record and must commit manually. The summary is the handoff document. Print to the user: - **Branch**: name + base ref. -- **PR**: `` (captured from step 14.5). - **Per-file table**: | File | Stubs impl. | Targeted tests | Reg. sweep impact | Reviewer | Issue | @@ -390,20 +342,57 @@ Print to the user: | `Extensions.cs` | … | … | … | … | … | - **Branch-wide totals**: - - Files modified (sum of production + tests + sibling fixtures touched). `.team-notes/` are gitignored and not committed. + - Files modified (sum of production + tests + sibling fixtures touched). `.team-notes/` are gitignored and stay local automatically. - Full solution test count (e.g. `1082/1082`). - Unresolved reviewer findings (if any). - Spec-text-only methods flagged separately (grounded in spec prose, not OCL). - - Out-of-scope blockers surfaced (e.g. "VerifyComputeX in TestFixture - is still stub-blocked on `` — consider a follow-up issue"). + - Out-of-scope blockers surfaced. -- **Commit message used** (informational — the commit is already on the branch): +- **Pre-filled commit message** (MANDATORY — append at the very end of the final-summary message in a fenced code block, ready to copy): ``` Fix # # # … ``` -- **PR is the review surface.** The user reviews the PR on GitHub — do not ask them to review `git diff` locally. + Single line. No body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer. The numbers are exactly the GitHub issue numbers handled by this batch, in the original `$ARGUMENTS` order (or, if the user expressed a preferred order in the invocation prompt, that order). + +- **Explicit handoff line** — the orchestrator must include this verbatim at the bottom: + + > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push the branch and open the PR. + +### 15. Phase PR — Push + open PR (MANDATORY, runs AFTER user's commit) + +Phase PR is non-skippable but does NOT run automatically as part of step 14. It runs only after the user replies to the handoff line in step 14 indicating that they have committed. The orchestrator must NEVER run `git commit` itself. + +When the user pings (`pushed` / `pr` / `commit done` / equivalent): + +1. **Verify the commit landed on the current feature branch**: + ```bash + git branch --show-current + git log -1 --oneline + git status --porcelain + ``` + - The current branch must NOT be `development` or `master` — ABORT with a hard refusal if it is. Feature work belongs on a feature branch. + - `git log -1` should show a commit whose message matches the canonical `Fix # # …` form. If it doesn't (user used a different message), surface that to the user and ask whether to push as-is or wait while they amend. Do NOT auto-amend. + - `git status --porcelain` should be empty. If it isn't, surface to the user — there are uncommitted changes that shouldn't get left behind. + +2. **Push** the branch to `origin`: + ```bash + git push -u origin + ``` + NEVER `--force`. NEVER `--force-with-lease`. NEVER `--no-verify`. If the push is rejected because the branch diverged from origin, surface the conflict and stop. + +3. **Open the PR** against `development`: + ```bash + gh pr create --base development --head \ + --title "Fix # # # …" \ + --body-file + ``` + The PR body is the per-file table + branch-wide totals from step 14. NEVER use `--draft` unless the user explicitly asked. NEVER use `--base master`. + +4. **Capture the PR URL** from `gh pr create`'s stdout and report it back to the user. + +If the user replies with something other than the commit confirmation (e.g. "rerun the tests", "amend the fix"), the orchestrator stays in handoff mode and serves that request — Phase PR runs only after the user confirms commit. ## Failure handling @@ -422,10 +411,12 @@ Print to the user: | Reviewer NEEDS FIX for one or more files | Step 12 | Re-dispatch THE implementer or THE tester with a focused brief naming the broken file(s); other files' results still reported. | | Implementer's context runs out mid-batch | Any IT/V step | Re-dispatch THE implementer with a focused brief covering only the unfinished file(s). Partial progress on disk is preserved. | | Batch partially fails after branch + assignment | Any step ≥ 6 | Keep the branch; surface in final summary; user decides whether to retry via `/implement-extensions` for the still-broken single file or revert. | -| `git push` rejected (branch diverged from origin) | Phase PR (step 14.3) | Abort the push, surface to user, do NOT force-push. | -| `gh pr create` fails (no GitHub auth, repo write permission missing) | Phase PR (step 14.4) | Surface the gh error, leave the branch pushed, advise the user to open the PR manually. | -| Working tree contains files outside the in-scope list at Phase PR | Phase PR (step 14.1) | Refuse to stage them in the `Fix #…` commit. Either split into a separate follow-up commit on the same branch or surface to the user. | -| Current branch is `development` or `master` at Phase PR | Phase PR (defensive) | ABORT the workflow — feature work belongs on a feature branch. Surface to the user. | +| `git push` rejected (branch diverged from origin) | Phase PR (step 15.2) | Abort the push, surface to user, do NOT force-push. | +| `gh pr create` fails (no GitHub auth, repo write permission missing) | Phase PR (step 15.3) | Surface the gh error, leave the branch pushed, advise the user to open the PR manually. | +| User's commit message doesn't match `Fix #…` form | Phase PR (step 15.1) | Surface the divergence, ask whether to push as-is or wait while they amend. Do NOT auto-amend. | +| Working tree non-empty at Phase PR (`git status --porcelain` non-empty) | Phase PR (step 15.1) | Surface to the user — there are uncommitted changes that need to be addressed before push. | +| Current branch is `development` or `master` at Phase PR | Phase PR (defensive, step 15.1) | ABORT the workflow — feature work belongs on a feature branch. Surface to the user. | +| User asks for follow-up work instead of confirming commit | After step 14 | Stay in handoff mode, serve the follow-up request; do NOT run Phase PR until the user explicitly confirms commit. | ## Parallelism caps (orchestrator self-enforced) @@ -453,7 +444,8 @@ context per role. mistranslation. - The branch and the assignments persist even on partial failure. Be explicit in the final summary about which files succeeded vs which need follow-up. -- **Phase PR is MANDATORY** (step 14). Commit + push + open PR at the end of every batch run. The PR is the user's review surface; do NOT ask the user to review `git diff` and commit manually. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". +- **Commit is the user's job** — agent NEVER runs `git commit`. Step 14 (final summary) ends with a pre-filled commit message and an explicit handoff line; the user reviews `git diff`, stages, commits, and pings the agent back. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". +- **Phase PR (step 15) is MANDATORY** after the user's commit confirmation. The agent verifies the commit landed, then pushes the branch (`git push -u origin `) and opens the PR (`gh pr create --base development`). Refuse if the current branch is `development` or `master`. - If the user supplies a single file, route them to `/implement-extensions` with the same filename rather than creating a degenerate 1-file "batch" branch. diff --git a/.claude/commands/implement-extensions.md b/.claude/commands/implement-extensions.md index 73fa64b0..f071a8be 100644 --- a/.claude/commands/implement-extensions.md +++ b/.claude/commands/implement-extensions.md @@ -367,7 +367,9 @@ verdict. If the verdict is "NEEDS FIX", dispatch the implementer or tester back to action the findings (the reviewer never edits). -### 10. Final summary +### 10. Final summary + commit-ready handoff + +After step 11 (issue checklist sync) completes, the orchestrator stops and surfaces the final summary. **The orchestrator does NOT run `git add` or `git commit`** — the user is the reviewer of record and must commit manually. Report to the user: - Modified files (production + test fixture + notes + any regression-sweep test fixtures). @@ -380,8 +382,8 @@ Report to the user: knows the implementation is grounded in spec prose rather than OCL. - **Issue checklist sync**: `` — `` newly ticked, `` newly added, `/` total (filled in after step 11). -- **PR URL**: `` (captured in step 12 / Phase PR). -- **Commit message used** (informational — the commit is already on the branch): +- **Pre-filled commit message** (MANDATORY — append at the very end of the + final-summary message in a fenced code block, ready to copy): ``` Fix # @@ -391,7 +393,11 @@ Report to the user: no body paragraphs, no per-method bullet list, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer. The single line is the entire message. -The PR is the user's review surface — do NOT ask them to review `git diff` and commit manually. See CLAUDE.md "Branch & PR workflow (MANDATORY)" and `feedback_pr_mandatory.md`. +- **Explicit handoff line** — the orchestrator must include this verbatim at the bottom: + + > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push the branch and open the PR. + +See CLAUDE.md "Branch & PR workflow (MANDATORY)" and `feedback_pr_mandatory.md`. ### 11. Sync GitHub issue checklist @@ -452,49 +458,39 @@ unresolved findings are separately surfaced in the final-summary report. The newly ticked items, count of newly added items, and the resulting `/` ratio. -### 12. Phase PR — Commit, push, open PR (MANDATORY when on a non-development branch) - -This phase is non-skippable. Every `/implement-extensions` run ends with a pushed branch and an open PR against `development`. See the user-memory rule `feedback_pr_mandatory.md` and the CLAUDE.md "Branch & PR workflow (MANDATORY)" section. - -**Defensive guard**: check the current branch first. - -```bash -git branch --show-current -``` - -If it is `development` or `master`, ABORT — surface a hard refusal to the user. Feature work belongs on a feature branch first; the user should `git switch -c ` then re-invoke. Do NOT push. +### 12. Phase PR — Push + open PR (MANDATORY, runs AFTER user's commit) -Otherwise: +Phase PR is non-skippable but does NOT run automatically as part of step 10/11. It runs only after the user replies to the handoff line in step 10 indicating that they have committed. The orchestrator **must NEVER** run `git commit` itself. -1. **Stage in-scope files EXPLICITLY** — NEVER `git add -A` / `git add .`: - ```bash - git add SysML2.NET/Extend/Extensions.cs \ - SysML2.NET.Tests/Extend/ExtensionsTestFixture.cs \ - - ``` - `.team-notes/` is gitignored so it stays local automatically. +When the user pings (`pushed` / `pr` / `commit done` / equivalent): -2. **Commit** with the canonical single-issue message: +1. **Verify the commit landed on the current feature branch**: ```bash - git commit -m "Fix #" + git branch --show-current + git log -1 --oneline + git status --porcelain ``` - Single line, no body, no trailers, no `--no-verify`. + - The current branch must NOT be `development` or `master` — ABORT with a hard refusal if it is. Feature work belongs on a feature branch; the user should `git switch -c ` and re-commit there. + - `git log -1` should show a commit whose message matches the canonical `Fix #` form. If it doesn't (user used a different message), surface that to the user and ask whether to push as-is or wait while they amend. Do NOT auto-amend. + - `git status --porcelain` should be empty. If it isn't, surface to the user — there are uncommitted changes that need to be addressed before push. -3. **Push** the branch: +2. **Push** the branch to `origin`: ```bash git push -u origin ``` - NEVER `--force` / `--force-with-lease`. If push is rejected because the branch diverged, surface the conflict and stop. + NEVER `--force` / `--force-with-lease` / `--no-verify`. If push is rejected because the branch diverged, surface the conflict and stop. -4. **Open PR** against `development`: +3. **Open PR** against `development`: ```bash gh pr create --base development --head \ --title "Fix #" \ --body-file ``` - PR body is the per-method test result + reviewer verdict from step 10. NEVER `--base master`. + PR body is the per-method test result + reviewer verdict from step 10. NEVER `--base master`. NEVER `--draft` unless the user asked. + +4. **Capture the PR URL** and report it back to the user. -5. **Capture the PR URL** and feed it back into the step-10 final-summary line. +If the user replies with something other than the commit confirmation (e.g. "rerun the tests", "amend the fix"), the orchestrator stays in handoff mode and serves that request — Phase PR runs only after the user explicitly confirms commit. ## Notes for the orchestrator (you, the main agent) @@ -526,7 +522,8 @@ Otherwise: implementation state of the file; unresolved findings are separately surfaced in the final-summary report. The `gh issue edit` push must touch ONLY the `### Checklist` section — verify with a re-fetch + diff before reporting "done". -- **Phase PR (step 12) is MANDATORY.** Commit + push + open PR at the end of every run. The PR is the user's review surface; do NOT ask the user to review `git diff` and commit manually. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". Refuse to push if the current branch is `development` or `master`. +- **Commit is the user's job** — the agent NEVER runs `git commit`. Step 10 (final summary) ends with a pre-filled commit message and an explicit handoff line; the user reviews `git diff`, stages, commits, and pings the agent back. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". +- **Phase PR (step 12) is MANDATORY** after the user's commit confirmation. The agent verifies the commit landed (right branch, message matches, working tree empty), then pushes the branch (`git push -u origin `) and opens the PR (`gh pr create --base development`). Refuse if the current branch is `development` or `master`. - **Plan mode is handled by Gate 0 at the top of this file** — the orchestrator writes the proposed-execution plan to the plan file, calls `ExitPlanMode`, and proceeds on approval. The orchestrator never spawns sub-agents while plan mode is active, so the previous "degraded mode" workaround is no longer needed and has been removed. - **Gate R-A (step 5.5) is mandatory every run.** It is the only structural checkpoint between the researcher returning `spec ready` and the implementer + tester being spawned. Do not skip it even when the researcher reports zero ambiguities — the user explicitly asked for an unconditional gate so they can review per-method derivations before code is written. - **Tool-level prompts (`Bash(...)`, `Edit(...)`, `Write(...)`, `Agent(...)`) still surface per the user's `settings.json`.** Gate 0 and Gate R-A govern STRUCTURAL approval only. The user has explicitly chosen to keep handling tool-level prompts manually rather than auto-allowing them via permission rules or hooks. diff --git a/CLAUDE.md b/CLAUDE.md index bf632861..d0863e6b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -150,22 +150,29 @@ Auto-generated DTOs use structured namespaces reflecting the KerML/SysML package ## Branch & PR workflow (MANDATORY) -Every branch must be pushed and have an open PR against `development` before any task is reported "done". The PR is the user's review surface — the agent does NOT ask the user to review `git diff` manually before committing. Direct pushes to `development` or `master` are forbidden. +Every branch must be pushed and have an open PR against `development` before any task is reported "done". Direct pushes to `development` or `master` are forbidden. The agent **must NOT auto-commit** — `git commit` is the user's responsibility; the user reviews `git diff` and commits manually. After the user's commit is on the branch, the agent **must** push the branch and open the PR. Operationally, at the end of any task that creates a branch (most commonly `/implement-extensions` and `/implement-extensions-batch`): -1. **Stage in-scope files explicitly** — `git add …`. NEVER `git add -A` or `git add .` (sensitive files / drift can leak). -2. **Commit** with the canonical short message: `Fix #` for single-issue runs, `Fix # # …` for batches. Single line. No body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer, no `--no-verify`. -3. **Push**: `git push -u origin `. NEVER `--force`, NEVER `--force-with-lease`. -4. **Open PR**: `gh pr create --base development --head --title "Fix #…" --body-file `. Capture the PR URL and surface it in the final summary. +1. **Agent stops** with a final summary that: + - lists the in-scope files modified, the test counts, the reviewer verdict, etc., + - surfaces a **pre-filled commit message** (`Fix #` for single-issue runs, `Fix # # …` for batches — single line, no body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer), + - explicitly tells the user: "Review `git diff`, stage the in-scope files explicitly (NEVER `git add -A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push + open the PR." +2. **User reviews and commits** — entirely manual, agent does not run `git commit`. +3. **User pings the agent** that the commit is on the branch. +4. **Agent verifies** the commit is on the current feature branch (`git log -1` matches the pre-filled message; `git status --porcelain` reports nothing) and only then: + - `git push -u origin ` — NEVER `--force`, NEVER `--force-with-lease`, NEVER `--no-verify`. + - `gh pr create --base development --head --title "Fix #…" --body-file ` — NEVER `--base master`, NEVER `--draft` unless the user asked. + - Capture and report the PR URL. 5. **If the current branch is `development` or `master`**: REFUSE the workflow. Surface to the user — feature work must live on a feature branch first. Failure modes: - `git push` rejected (branch diverged from origin) → abort, surface, do NOT force-push. - `gh pr create` fails (no auth, no write permission) → leave the branch pushed, advise the user to open the PR manually. -- Mid-task non-payload edits (e.g. instruction-file updates surfaced during a batch) → split into separate commits on the same branch so the `Fix #…` commit carries only the issue-resolving payload. +- User's commit message deviates from the canonical short form → surface to the user, ask whether they want to amend or push as-is. Do NOT auto-amend. +- Mid-task non-payload edits (e.g. instruction-file updates surfaced during a batch) → carry them in a separate user-made commit on the same branch so the `Fix #…` commit carries only the issue-resolving payload. -This policy reverses any older slash-command snippet that says "Do NOT auto-commit; the user reviews `git diff` and commits manually" — those snippets have been superseded by Phase PR. +**Why the split**: the user is the reviewer of record. The commit IS the review. The PR + push is just delivery. Reversing this — auto-committing on the user's behalf — bypasses the review and has been explicitly rejected as policy. ## Quality rules From b373812a5fd0275045af29fa02f6bf656b46e176 Mon Sep 17 00:00:00 2001 From: atheate Date: Fri, 29 May 2026 13:53:25 +0200 Subject: [PATCH 3/3] remove PR creation part --- .../commands/implement-extensions-batch.md | 67 +++++-------------- .claude/commands/implement-extensions.md | 46 ++----------- CLAUDE.md | 51 +++++++------- 3 files changed, 52 insertions(+), 112 deletions(-) diff --git a/.claude/commands/implement-extensions-batch.md b/.claude/commands/implement-extensions-batch.md index 5eb5faae..ff294312 100644 --- a/.claude/commands/implement-extensions-batch.md +++ b/.claude/commands/implement-extensions-batch.md @@ -186,14 +186,18 @@ batch-impl-extensions- - If more than 4 issues: include the first 4 + `-plus` suffix (e.g. `batch-impl-extensions-123-180-186-190-plus2` for N=6). -Create: +Create the local branch AND immediately push the empty ref to `origin`: + ```bash git switch -c origin/development +git push -u origin ``` -Refuse if the branch already exists locally OR on origin (`git ls-remote ---exit-code origin `) — ask the user to pick a different batch or delete -the stale branch. +The second push is safe: the branch tip equals `origin/development`'s tip, so no commits are pushed — just the ref is created on origin. This is the only push the orchestrator performs by default; it exists so the user's later `git push` of their own commit is a trivial fast-forward with no `-u` setup hassle. + +Refuse if the branch already exists locally OR on origin (`git ls-remote --exit-code origin `) — ask the user to pick a different batch or delete the stale branch. + +If `git push -u origin ` fails (e.g. no GitHub auth, no write permission), surface the error and continue with the local branch only — the user will set up the remote ref themselves later. ### 7. Assign every issue to `@me` @@ -327,13 +331,13 @@ step-11 logic from `/implement-extensions`: 6. Push via `gh issue edit --body-file `. 7. Re-fetch + diff to verify only the Checklist section changed. -### 14. Final summary + commit-ready handoff +### 14. Final summary + commit-ready handoff (END OF RUN) -After Phase IS completes, the orchestrator stops and surfaces a final summary. **The orchestrator does NOT run `git add` or `git commit`** — the user is the reviewer of record and must commit manually. The summary is the handoff document. +After Phase IS completes, the orchestrator stops. **This is the end of the batch run.** The orchestrator does NOT run `git add`, does NOT run `git commit`, does NOT push the user's commit, does NOT open the PR. Those are entirely the user's job. The agent's git involvement was bounded to step 6 (create branch locally + push empty ref). Print to the user: -- **Branch**: name + base ref. +- **Branch**: name + base ref. Note that the empty branch was already pushed to `origin/` in step 6, so the user's `git push` of their own commit will be a trivial fast-forward. - **Per-file table**: | File | Stubs impl. | Targeted tests | Reg. sweep impact | Reviewer | Issue | @@ -358,41 +362,9 @@ Print to the user: - **Explicit handoff line** — the orchestrator must include this verbatim at the bottom: - > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push the branch and open the PR. - -### 15. Phase PR — Push + open PR (MANDATORY, runs AFTER user's commit) - -Phase PR is non-skippable but does NOT run automatically as part of step 14. It runs only after the user replies to the handoff line in step 14 indicating that they have committed. The orchestrator must NEVER run `git commit` itself. - -When the user pings (`pushed` / `pr` / `commit done` / equivalent): - -1. **Verify the commit landed on the current feature branch**: - ```bash - git branch --show-current - git log -1 --oneline - git status --porcelain - ``` - - The current branch must NOT be `development` or `master` — ABORT with a hard refusal if it is. Feature work belongs on a feature branch. - - `git log -1` should show a commit whose message matches the canonical `Fix # # …` form. If it doesn't (user used a different message), surface that to the user and ask whether to push as-is or wait while they amend. Do NOT auto-amend. - - `git status --porcelain` should be empty. If it isn't, surface to the user — there are uncommitted changes that shouldn't get left behind. - -2. **Push** the branch to `origin`: - ```bash - git push -u origin - ``` - NEVER `--force`. NEVER `--force-with-lease`. NEVER `--no-verify`. If the push is rejected because the branch diverged from origin, surface the conflict and stop. - -3. **Open the PR** against `development`: - ```bash - gh pr create --base development --head \ - --title "Fix # # # …" \ - --body-file - ``` - The PR body is the per-file table + branch-wide totals from step 14. NEVER use `--draft` unless the user explicitly asked. NEVER use `--base master`. - -4. **Capture the PR URL** from `gh pr create`'s stdout and report it back to the user. + > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then `git push` (the remote branch already exists from step 6, so this is a fast-forward — no `-u` needed). Open the PR yourself via the GitHub UI or `gh pr create --base development`. -If the user replies with something other than the commit confirmation (e.g. "rerun the tests", "amend the fix"), the orchestrator stays in handoff mode and serves that request — Phase PR runs only after the user confirms commit. +After the handoff line, the orchestrator stops. The run is complete. The user may follow up with a separate request (e.g. "rerun the tests", "amend the fix") which the orchestrator serves as a new turn — but the agent does NOT proactively push, PR, or commit. If the user explicitly asks the agent to push or open the PR, the agent does so per the CLAUDE.md "Branch & PR workflow (MANDATORY)" → "If the user does explicitly ask the agent to push or open the PR" subsection. ## Failure handling @@ -411,12 +383,9 @@ If the user replies with something other than the commit confirmation (e.g. "rer | Reviewer NEEDS FIX for one or more files | Step 12 | Re-dispatch THE implementer or THE tester with a focused brief naming the broken file(s); other files' results still reported. | | Implementer's context runs out mid-batch | Any IT/V step | Re-dispatch THE implementer with a focused brief covering only the unfinished file(s). Partial progress on disk is preserved. | | Batch partially fails after branch + assignment | Any step ≥ 6 | Keep the branch; surface in final summary; user decides whether to retry via `/implement-extensions` for the still-broken single file or revert. | -| `git push` rejected (branch diverged from origin) | Phase PR (step 15.2) | Abort the push, surface to user, do NOT force-push. | -| `gh pr create` fails (no GitHub auth, repo write permission missing) | Phase PR (step 15.3) | Surface the gh error, leave the branch pushed, advise the user to open the PR manually. | -| User's commit message doesn't match `Fix #…` form | Phase PR (step 15.1) | Surface the divergence, ask whether to push as-is or wait while they amend. Do NOT auto-amend. | -| Working tree non-empty at Phase PR (`git status --porcelain` non-empty) | Phase PR (step 15.1) | Surface to the user — there are uncommitted changes that need to be addressed before push. | -| Current branch is `development` or `master` at Phase PR | Phase PR (defensive, step 15.1) | ABORT the workflow — feature work belongs on a feature branch. Surface to the user. | -| User asks for follow-up work instead of confirming commit | After step 14 | Stay in handoff mode, serve the follow-up request; do NOT run Phase PR until the user explicitly confirms commit. | +| Empty-branch push to origin fails | Step 6 | Surface the error and continue with the local branch only. The user sets up the remote ref themselves later. | +| User explicitly asks the agent to push their commit and the commit doesn't exist on the current branch | User-initiated push request | Refuse, surface — agent only pushes commits that are already on the branch (which the user made themselves). | +| User explicitly asks the agent to push and the current branch is `development`/`master` | User-initiated push request | REFUSE — feature work must live on a feature branch first. Surface to the user. | ## Parallelism caps (orchestrator self-enforced) @@ -444,8 +413,8 @@ context per role. mistranslation. - The branch and the assignments persist even on partial failure. Be explicit in the final summary about which files succeeded vs which need follow-up. -- **Commit is the user's job** — agent NEVER runs `git commit`. Step 14 (final summary) ends with a pre-filled commit message and an explicit handoff line; the user reviews `git diff`, stages, commits, and pings the agent back. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". -- **Phase PR (step 15) is MANDATORY** after the user's commit confirmation. The agent verifies the commit landed, then pushes the branch (`git push -u origin `) and opens the PR (`gh pr create --base development`). Refuse if the current branch is `development` or `master`. +- **Commit is the user's job** — agent NEVER runs `git commit`, ever. Step 14 (final summary) ends with a pre-filled commit message + handoff line, then the run is over. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". +- **Push + PR are the user's job too** — the agent does NOT proactively push commits or open PRs. It only performs those if the user explicitly asks in a follow-up turn. The one push the agent does perform by default is the empty-branch push in step 6 (creating the remote ref at the same tip as `origin/development`, so the user's later push of their own commit is a trivial fast-forward). - If the user supplies a single file, route them to `/implement-extensions` with the same filename rather than creating a degenerate 1-file "batch" branch. diff --git a/.claude/commands/implement-extensions.md b/.claude/commands/implement-extensions.md index f071a8be..fc941a89 100644 --- a/.claude/commands/implement-extensions.md +++ b/.claude/commands/implement-extensions.md @@ -367,9 +367,9 @@ verdict. If the verdict is "NEEDS FIX", dispatch the implementer or tester back to action the findings (the reviewer never edits). -### 10. Final summary + commit-ready handoff +### 10. Final summary + commit-ready handoff (END OF RUN) -After step 11 (issue checklist sync) completes, the orchestrator stops and surfaces the final summary. **The orchestrator does NOT run `git add` or `git commit`** — the user is the reviewer of record and must commit manually. +After step 11 (issue checklist sync) completes, the orchestrator stops. **This is the end of the run.** The orchestrator does NOT run `git add`, does NOT run `git commit`, does NOT push the user's commit, does NOT open the PR. Those are entirely the user's job. Report to the user: - Modified files (production + test fixture + notes + any regression-sweep test fixtures). @@ -395,9 +395,9 @@ Report to the user: - **Explicit handoff line** — the orchestrator must include this verbatim at the bottom: - > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push the branch and open the PR. + > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then `git push` (if the remote branch ref does not yet exist, use `git push -u origin ` once). Open the PR yourself via the GitHub UI or `gh pr create --base development`. -See CLAUDE.md "Branch & PR workflow (MANDATORY)" and `feedback_pr_mandatory.md`. +After the handoff line, the orchestrator stops. The run is complete. If the user explicitly asks in a follow-up turn for the agent to push their commit or open the PR, the agent does so per the CLAUDE.md "Branch & PR workflow (MANDATORY)" → "If the user does explicitly ask the agent to push or open the PR" subsection. Otherwise the user handles those steps themselves. See `feedback_pr_mandatory.md`. ### 11. Sync GitHub issue checklist @@ -458,40 +458,6 @@ unresolved findings are separately surfaced in the final-summary report. The newly ticked items, count of newly added items, and the resulting `/` ratio. -### 12. Phase PR — Push + open PR (MANDATORY, runs AFTER user's commit) - -Phase PR is non-skippable but does NOT run automatically as part of step 10/11. It runs only after the user replies to the handoff line in step 10 indicating that they have committed. The orchestrator **must NEVER** run `git commit` itself. - -When the user pings (`pushed` / `pr` / `commit done` / equivalent): - -1. **Verify the commit landed on the current feature branch**: - ```bash - git branch --show-current - git log -1 --oneline - git status --porcelain - ``` - - The current branch must NOT be `development` or `master` — ABORT with a hard refusal if it is. Feature work belongs on a feature branch; the user should `git switch -c ` and re-commit there. - - `git log -1` should show a commit whose message matches the canonical `Fix #` form. If it doesn't (user used a different message), surface that to the user and ask whether to push as-is or wait while they amend. Do NOT auto-amend. - - `git status --porcelain` should be empty. If it isn't, surface to the user — there are uncommitted changes that need to be addressed before push. - -2. **Push** the branch to `origin`: - ```bash - git push -u origin - ``` - NEVER `--force` / `--force-with-lease` / `--no-verify`. If push is rejected because the branch diverged, surface the conflict and stop. - -3. **Open PR** against `development`: - ```bash - gh pr create --base development --head \ - --title "Fix #" \ - --body-file - ``` - PR body is the per-method test result + reviewer verdict from step 10. NEVER `--base master`. NEVER `--draft` unless the user asked. - -4. **Capture the PR URL** and report it back to the user. - -If the user replies with something other than the commit confirmation (e.g. "rerun the tests", "amend the fix"), the orchestrator stays in handoff mode and serves that request — Phase PR runs only after the user explicitly confirms commit. - ## Notes for the orchestrator (you, the main agent) - Pick the model per role using the complexity-grading rubric in step 3.5. @@ -522,8 +488,8 @@ If the user replies with something other than the commit confirmation (e.g. "rer implementation state of the file; unresolved findings are separately surfaced in the final-summary report. The `gh issue edit` push must touch ONLY the `### Checklist` section — verify with a re-fetch + diff before reporting "done". -- **Commit is the user's job** — the agent NEVER runs `git commit`. Step 10 (final summary) ends with a pre-filled commit message and an explicit handoff line; the user reviews `git diff`, stages, commits, and pings the agent back. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". -- **Phase PR (step 12) is MANDATORY** after the user's commit confirmation. The agent verifies the commit landed (right branch, message matches, working tree empty), then pushes the branch (`git push -u origin `) and opens the PR (`gh pr create --base development`). Refuse if the current branch is `development` or `master`. +- **Commit is the user's job** — the agent NEVER runs `git commit`, ever. Step 10 (final summary) ends with a pre-filled commit message + handoff line, then the run is over. See `feedback_pr_mandatory.md` and CLAUDE.md "Branch & PR workflow (MANDATORY)". +- **Push + PR are the user's job too** — the agent does NOT proactively push commits or open PRs. It only performs those if the user explicitly asks in a follow-up turn (rare; user-initiated only). Unlike `/implement-extensions-batch`, this command does NOT create a branch, so there is no empty-branch push to perform — the user owns branch creation and remote setup. - **Plan mode is handled by Gate 0 at the top of this file** — the orchestrator writes the proposed-execution plan to the plan file, calls `ExitPlanMode`, and proceeds on approval. The orchestrator never spawns sub-agents while plan mode is active, so the previous "degraded mode" workaround is no longer needed and has been removed. - **Gate R-A (step 5.5) is mandatory every run.** It is the only structural checkpoint between the researcher returning `spec ready` and the implementer + tester being spawned. Do not skip it even when the researcher reports zero ambiguities — the user explicitly asked for an unconditional gate so they can review per-method derivations before code is written. - **Tool-level prompts (`Bash(...)`, `Edit(...)`, `Write(...)`, `Agent(...)`) still surface per the user's `settings.json`.** Gate 0 and Gate R-A govern STRUCTURAL approval only. The user has explicitly chosen to keep handling tool-level prompts manually rather than auto-allowing them via permission rules or hooks. diff --git a/CLAUDE.md b/CLAUDE.md index d0863e6b..18c5b0f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -150,29 +150,34 @@ Auto-generated DTOs use structured namespaces reflecting the KerML/SysML package ## Branch & PR workflow (MANDATORY) -Every branch must be pushed and have an open PR against `development` before any task is reported "done". Direct pushes to `development` or `master` are forbidden. The agent **must NOT auto-commit** — `git commit` is the user's responsibility; the user reviews `git diff` and commits manually. After the user's commit is on the branch, the agent **must** push the branch and open the PR. - -Operationally, at the end of any task that creates a branch (most commonly `/implement-extensions` and `/implement-extensions-batch`): - -1. **Agent stops** with a final summary that: - - lists the in-scope files modified, the test counts, the reviewer verdict, etc., - - surfaces a **pre-filled commit message** (`Fix #` for single-issue runs, `Fix # # …` for batches — single line, no body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer), - - explicitly tells the user: "Review `git diff`, stage the in-scope files explicitly (NEVER `git add -A` / `.`), commit with the message above, then reply `pushed` (or `pr` / `commit done`) and I'll push + open the PR." -2. **User reviews and commits** — entirely manual, agent does not run `git commit`. -3. **User pings the agent** that the commit is on the branch. -4. **Agent verifies** the commit is on the current feature branch (`git log -1` matches the pre-filled message; `git status --porcelain` reports nothing) and only then: - - `git push -u origin ` — NEVER `--force`, NEVER `--force-with-lease`, NEVER `--no-verify`. - - `gh pr create --base development --head --title "Fix #…" --body-file ` — NEVER `--base master`, NEVER `--draft` unless the user asked. - - Capture and report the PR URL. -5. **If the current branch is `development` or `master`**: REFUSE the workflow. Surface to the user — feature work must live on a feature branch first. - -Failure modes: -- `git push` rejected (branch diverged from origin) → abort, surface, do NOT force-push. -- `gh pr create` fails (no auth, no write permission) → leave the branch pushed, advise the user to open the PR manually. -- User's commit message deviates from the canonical short form → surface to the user, ask whether they want to amend or push as-is. Do NOT auto-amend. -- Mid-task non-payload edits (e.g. instruction-file updates surfaced during a batch) → carry them in a separate user-made commit on the same branch so the `Fix #…` commit carries only the issue-resolving payload. - -**Why the split**: the user is the reviewer of record. The commit IS the review. The PR + push is just delivery. Reversing this — auto-committing on the user's behalf — bypasses the review and has been explicitly rejected as policy. +Direct pushes to `development` or `master` are forbidden. All work lives on a feature branch. + +**Agent boundaries are strict and minimal**: + +1. The agent **must NOT auto-commit, EVER.** `git commit` is the user's responsibility — no exceptions, no asking, no "for convenience". The user reviews `git diff` and commits manually. +2. The agent **must NOT push commits, open PRs, or merge by default.** Push + PR + merge are the user's job too. The agent only performs push/PR if the user explicitly asks for them in-conversation; otherwise it stays out of git remote operations entirely. +3. **When the agent creates a branch** (typically inside `/implement-extensions-batch` step 6), it must: + - create it locally with `git switch -c origin/development`, AND + - **immediately push the empty branch to `origin`** with `git push -u origin `, so the remote ref exists at the same commit as `origin/development` and the user's later push of the actual commit becomes a trivial fast-forward. + This is the only push the agent performs by default. It is safe because the branch tip equals `origin/development`'s tip — no new commits, no force flags, no risk of overwriting. +4. **At the end of any task that creates a branch**, the agent stops with a final summary that includes: + - the in-scope files modified, the test counts, the reviewer verdict, etc., + - a **pre-filled commit message** (`Fix #` for single-issue runs, `Fix # # …` for batches — single line, no body, no `Co-Authored-By` trailer, no "🤖 Generated with …" footer), + - a handoff line telling the user how to stage + commit + push the resulting commit themselves. Example: + > Review `git diff`, stage the in-scope files (`git add …` — NEVER `-A` / `.`), commit with the message above, then `git push` (the remote branch already exists, so this is a fast-forward — no `-u` needed). Open the PR yourself via the GitHub UI or `gh pr create --base development`. + - This is the end of the agent's involvement. **The agent does NOT proceed to push the commit, does NOT open the PR**, unless the user explicitly asks. Typical case: the user handles both. + +**If the user does explicitly ask the agent to push or open the PR** (rare; user-initiated only): +- The agent verifies: current branch is not `development`/`master`, `git log -1` matches the canonical `Fix #…` form, `git status --porcelain` is empty. +- Then `git push origin ` — NEVER `--force`, NEVER `--force-with-lease`, NEVER `--no-verify`. +- Then `gh pr create --base development --head --title "Fix #…" --body-file ` — NEVER `--base master`, NEVER `--draft` unless the user asked. + +**Failure modes**: +- `git push -u origin ` (step 3) fails because the branch already exists on origin → abort, surface to user, do not force. +- Branch creation requested but the current branch is `development` or `master` AND the user asked for in-place work → REFUSE. Feature work must live on a feature branch first. +- If the user asks the agent to push a commit and that commit was made by the agent (somehow), refuse and surface the policy violation. The agent's commits are forbidden by construction; if one exists, it is a bug that needs human review. + +**Why this split**: the user is the reviewer of record. The commit is the review and the push is the delivery — both are the user's calls. The agent's git involvement is bounded to: (a) create the branch locally + push the empty ref (so the user's push later is frictionless), and (b) leave the rest alone. This was tightened after two failures: first the agent auto-pushed branches to `development` directly, then over-corrected by auto-committing on the user's behalf. ## Quality rules