mandrel 1.57.0

package/.agents/workflows/git-merge-pr.md

@@ -0,0 +1,377 @@
+---
+description: >-
+  Analyze, validate, resolve conflicts, and merge a given pull request by
+  number.
+---
+
+# /git-merge-pr [#PR_LIST]
+
+This workflow performs a full end-to-end merge of one or more pull requests: it
+analyzes each PR diff, validates linting and tests, resolves any merge
+conflicts, and completes the merge into the target base branch.
+
+> **When to run**: Any time one or more PRs are ready for merge review and you
+> want an automated merge with conflict resolution and quality gates enforced.
+>
+> **Persona**: `devops-engineer` · **Skills**:
+> `core/git-workflow-and-versioning`
+
+---
+
+## Step 0 — Resolve Context
+
+1. Resolve one or more `[PR_NUMBER]` values from the slash-command argument
+   (e.g. `/git-merge-pr 42 43 45` → `PR_LIST=[42, 43, 45]`).
+2. **Sequential Loop**: Steps 1 through 7 must be performed **sequentially** for
+   each PR in the `PR_LIST`. Complete the full merge and cleanup for one PR
+   before starting the next.
+3. For the current `[PR_NUMBER]`, fetch metadata from GitHub by calling
+   `mcp__github__pull_request_read` (method `get`) with the repo's
+   `owner` / `repo` and `pullNumber: [PR_NUMBER]`. From the response, read
+   `number`, `title`, `headRefName`, `baseRefName`, `state`, `mergeable`,
+   and `mergeStateStatus`.
+
+4. From the output, resolve:
+   - `[PR_TITLE]` — the PR title.
+   - `[HEAD_BRANCH]` — the source branch (`headRefName`).
+   - `[BASE_BRANCH]` — the merge target (`baseRefName`).
+   - `[PR_STATE]` — must be `OPEN`. If `CLOSED` or `MERGED`, **SKIP** this PR
+     and proceed to the next one in the list.
+   - `[MERGEABLE]` — initial GitHub mergeability signal (`MERGEABLE`,
+     `CONFLICTING`, or `UNKNOWN`).
+
+---
+
+## Step 1 — PR Analysis
+
+Fetch the full diff and review the scope of changes:
+
+```powershell
+gh pr diff [PR_NUMBER]
+```
+
+> **Why `gh pr diff` and not MCP?** `mcp__github__pull_request_read`'s
+> `get_diff` method returns a structured response rather than the raw
+> unified diff this step renders to the operator. `gh pr diff` stays
+> until MCP exposes a raw-diff equivalent.
+
+Summarize the following to the operator before proceeding:
+
+- **Files changed** (count and list).
+- **Lines added / removed**.
+- **Areas of concern** — any files that touch shared utilities, schemas,
+  migrations, or critical infrastructure.
+- **Initial mergeability status** from Step 0.
+
+> This is a read-only analysis step. No files are modified yet.
+
+---
+
+## Step 2 — Checkout & Sync
+
+Delegate the rebase orchestration to `git-rebase-and-resolve.js`. It fetches
+`origin`, checks out the head branch, and rebases it onto the base — then
+reports the outcome in structured form so this skill routes on outcome
+instead of re-implementing the retry loop.
+
+```powershell
+node .agents/scripts/git-rebase-and-resolve.js --onto origin/[BASE_BRANCH] --head [HEAD_BRANCH] --json
+```
+
+Parse the JSON result. Route on `outcome`:
+
+- `clean` → rebase landed with no conflicts. Proceed to Step 3.
+- `conflict` → `conflictedFiles[]` lists the unmerged paths. Proceed to
+  Step 2.5.
+- `error` → git returned an error unrelated to conflicts. **STOP** and
+  surface `stderr` to the operator.
+
+### Step 2.5 — Conflict Resolution
+
+Follow the shared conflict-resolution procedure in
+[`helpers/_merge-conflict-template.md`](helpers/_merge-conflict-template.md):
+read both sides
+of each file in `conflictedFiles[]`, apply both when compatible (or choose a
+side with an explicit rationale), never silently drop code, then stage the
+resolutions.
+
+Continue the rebase via the script — it calls `git rebase --continue` and
+reports whether the rebase is now clean, still has conflicts (cascading
+conflict), or hit a different error:
+
+```powershell
+node .agents/scripts/git-rebase-and-resolve.js --continue --json
+```
+
+Loop until `outcome` is `continued`. If you need to bail out entirely:
+
+```powershell
+node .agents/scripts/git-rebase-and-resolve.js --abort --json
+```
+
+Once the rebase completes cleanly, force-push the rebased branch:
+
+```powershell
+git push --force-with-lease origin [HEAD_BRANCH]
+```
+
+---
+
+## Step 3 — Quality Gate (Lint + Format + Test)
+
+Run the full lint / format / test suite via the gate wrapper. The wrapper
+owns the command list so this skill doesn't rot when a project renames
+`lint` → `lint:ci` or swaps Biome for ESLint. The default check set is
+`lint`, `format:check`, `test`; override via `.agentrc.json → github.branchProtection`.
+
+```powershell
+node .agents/scripts/git-pr-quality-gate.js --json
+```
+
+The script emits a JSON result `{ ok, checks: [...], failed: [...] }`.
+Exit code 0 means every check passed. On failure:
+
+1. Read the `failed[]` entries (each has `name` and `reason`).
+2. For **format** failures, run `npx biome format --write .` to auto-fix,
+   then re-run the gate.
+3. For **lint** failures, apply the minimal manual fix.
+4. For **test** failures, classify before fixing:
+   - **Pre-existing failures** (unrelated to this PR's diff): alert the
+     operator and ask whether to proceed or block.
+   - **Regression introduced by this PR**: apply the fix.
+5. Commit the fixes and re-push:
+
+   ```powershell
+   git add .
+   # justification: post-CI remediation; CI lint+test gate ran upstream and produced the failure being fixed here. Local hook would re-run the same gate.
+   git commit --no-verify -m "fix(ci): resolve quality-gate failures on [HEAD_BRANCH] for PR #[PR_NUMBER]"
+   git push origin [HEAD_BRANCH]
+   ```
+
+6. Re-run the gate until it exits 0 before continuing to Step 3.5.
+
+> If a failure cannot be resolved after exhausting reasonable remediation
+> attempts, **STOP** and escalate to the operator with a detailed summary.
+
+---
+
+## Step 3.5 — Unified Baselines Gate (`check-baselines`)
+
+`check-baselines.js` is the single canonical floor + tolerance + schema
+gate for every baseline kind (coverage, crap, maintainability, mutation).
+It owns absolute-floor enforcement, schema validation, and kernel-mismatch
+surfacing. The per-kind regression CLIs that previously layered on top of
+this gate were removed in Epic #1943 — `check-baselines.js` is now the
+sole source of truth for baseline regressions at merge time.
+
+```powershell
+node .agents/scripts/check-baselines.js --format text
+```
+
+Exit codes:
+
+- `0` — every enabled gate's floors are met and no schema errors.
+- `1` — any floor breach. Inspect the JSON output
+  (`--format json`, the default) to see which kind / component / axis
+  fell below floor.
+- `2` — any baseline failed schema validation. Regenerate the offending
+  baseline through its per-kind update script.
+- `3` — config resolution error (typically a malformed `.agentrc.json`).
+
+Treat any non-zero exit as a hard merge block before proceeding to Step 4.
+
+---
+
+## Step 4 — Final Mergeability Check
+
+Re-query GitHub to confirm the PR is now clean and ready to merge by
+calling `mcp__github__pull_request_read` (method `get`) with the repo's
+`owner` / `repo` and `pullNumber: [PR_NUMBER]`. Read `mergeable`,
+`mergeStateStatus`, `reviewDecision`, and `statusCheckRollup` from the
+response (the same fields the prior `gh pr view --json` shape exposed).
+
+Verify:
+
+- `mergeable` is `MERGEABLE`.
+- `mergeStateStatus` is `CLEAN` or `HAS_HOOKS`.
+- Required CI checks (if any) are passing (`statusCheckRollup` → all `SUCCESS`
+  or `NEUTRAL`).
+
+If any blocking condition remains, resolve it before proceeding to the merge
+step.
+
+---
+
+## Step 5 — Merge
+
+Merge the PR as a squash commit and delete the head branch. Call
+`mcp__github__merge_pull_request` with the repo's `owner` / `repo`,
+`pullNumber: [PR_NUMBER]`, `merge_method: "squash"`, and
+`delete_branch: true`.
+
+> **MCP coverage gap — auto-merge queueing.** `mcp__github__merge_pull_request`
+> performs an **immediate** merge; it does not enable GitHub's native
+> auto-merge queue. When the workflow needs to queue the merge behind
+> required-check completion (the default `--auto` posture), fall back to
+> the shell form `gh pr merge [PR_NUMBER] --auto --squash --delete-branch`.
+> Use the MCP call when CI is already green and the merge can fire
+> synchronously (the common case after a clean Step 4 verdict).
+>
+> **Merge strategy guidance** (override with operator instruction):
+>
+> - `mcp__github__merge_pull_request` with `merge_method: "squash"` — the
+>   default for an already-green PR; clean history, single squash commit.
+> - `gh pr merge [PR_NUMBER] --auto --squash --delete-branch` — auto-merge
+>   queueing fallback when required checks are still pending. Requires
+>   `allow_auto_merge=true` on the repo (Story #1239 turns this on).
+> - `gh pr merge [PR_NUMBER] --squash` (no `--auto`) — synchronous merge;
+>   use only when bypassing auto-merge is intentional (e.g. CI is broken
+>   and a hotfix is going in under admin override).
+> - `--merge` — preserves the full commit history from `[HEAD_BRANCH]` (use for
+>   Epic branches with meaningful commit granularity); pass `merge_method:
+>   "merge"` to the MCP call or `--merge` to `gh pr merge`.
+> - `--rebase` — linear history; ideal for small, atomic PRs; pass
+>   `merge_method: "rebase"` to the MCP call or `--rebase` to `gh pr merge`.
+
+After the merge command returns, perform a conflict marker scan to confirm no
+stray markers entered the base branch. Delegate to `detect-merges.js` — it
+owns the scan logic and is the same script used by `/epic-deliver` Phase 5.3.
+
+```powershell
+git checkout [BASE_BRANCH]
+git pull origin [BASE_BRANCH]
+node .agents/scripts/detect-merges.js
+```
+
+If the script exits non-zero: **STOP**, alert the operator immediately, and
+do not proceed until the conflict markers are resolved.
+
+---
+
+## Step 6 — Post-Merge Verification & Cleanup
+
+Confirm the merge landed correctly on the base branch:
+
+```powershell
+git log origin/[BASE_BRANCH] -5 --oneline
+```
+
+Verify that the top commit corresponds to the merged PR.
+
+Explicitly delete the remote head branch. This is **mandatory** and must always
+succeed — even if the Husky pre-push hook blocks `git push origin --delete`. Use
+the **two-stage** approach below:
+
+**Stage 1 — git push (fast path):**
+
+```powershell
+# Attempt standard deletion first (fast, uses existing auth)
+git push origin --delete [HEAD_BRANCH] 2>$null
+$gitDeleteOk = $LASTEXITCODE -eq 0
+```
+
+**Stage 2 — REST API fallback (always run if Stage 1 failed):**
+
+If Stage 1 fails (exit code ≠ 0, e.g., due to Husky hook blocking the push),
+fall back to the GitHub REST API using the token from the git credential store:
+
+```powershell
+if (-not $gitDeleteOk) {
+  # Retrieve token from git's native credential manager
+  $creds = "protocol=https`nhost=github.com`n" | git credential fill 2>$null
+  $token = ($creds | Select-String 'password=(.+)').Matches[0].Groups[1].Value
+
+  if ($token) {
+    $url = "https://api.github.com/repos/[OWNER]/[REPO]/git/refs/heads/[HEAD_BRANCH]"
+    $headers = @{ Authorization = "token $token"; Accept = "application/vnd.github.v3+json" }
+    try {
+      Invoke-RestMethod -Method DELETE -Uri $url -Headers $headers -ErrorAction Stop
+      Write-Host "Remote branch deleted via REST API: [HEAD_BRANCH]"
+    } catch {
+      $status = $_.Exception.Response.StatusCode.value__
+      if ($status -eq 422 -or $status -eq 404) {
+        Write-Host "Branch already gone (HTTP $status) — skipping."
+      } else {
+        Write-Warning "Failed to delete remote branch via API (HTTP $status): [HEAD_BRANCH]"
+      }
+    }
+  } else {
+    Write-Warning "No GitHub token found in credential store — remote branch may not be deleted."
+  }
+}
+```
+
+Prune stale remote-tracking refs and delete the local branch:
+
+```powershell
+git fetch --prune
+git branch -D [HEAD_BRANCH] 2>$null
+```
+
+> **Note:** `git branch -D` is safe to ignore if the local branch does not
+> exist. `git fetch --prune` must always run to keep the local ref list clean.
+
+Explicitly close the GitHub PR object. Because this workflow squash-merges
+directly into the base branch (bypassing GitHub's native merge flow), GitHub
+**will not** auto-close the PR — it must be closed explicitly.
+
+Call `mcp__github__update_pull_request` with the repo's `owner` / `repo`,
+`pullNumber: [PR_NUMBER]`, and `state: "closed"`.
+
+> **Note:** This is a hard requirement — leaving the PR open after merging
+> pollutes the repository's open PR list and causes confusion for reviewers.
+
+Optionally, run the test suite one final time on the base branch to confirm no
+regressions were introduced by the merge:
+
+```powershell
+npm test
+```
+
+---
+
+## Step 7 — Summary Report
+
+Post a structured summary comment to the PR (now closed) for traceability.
+Call `mcp__github__add_issue_comment` with the repo's `owner` / `repo`,
+`issue_number: [PR_NUMBER]` (PR comments use the issues comments endpoint),
+and `body` set to:
+
+```markdown
+✅ **Merged by agent** via `/git-merge-pr`
+
+- **Branch**: `[HEAD_BRANCH]` → `[BASE_BRANCH]`
+- **Conflicts resolved**: [YES/NO — list files if YES]
+- **Lint fixes applied**: [YES/NO]
+- **Test fixes applied**: [YES/NO]
+- **Merge strategy**: squash
+```
+
+---
+
+## Constraint
+
+- **Never** merge a PR that has unresolved lint errors or failing tests. Running
+  a passing quality gate is mandatory before the merge commit.
+- **Never** silently drop code when resolving merge conflicts. When in doubt,
+  ask the operator.
+- **Never** bypass required GitHub branch protection checks (required reviewers,
+  required status checks). If these are blocking, surface them to the operator
+  rather than attempting to force-merge.
+- **Always** explicitly delete the remote head branch in Step 6 with
+  `git push origin --delete [HEAD_BRANCH]`. Do **not** rely solely on the
+  Step 5 merge call's `delete_branch` flag (whether passed via
+  `mcp__github__merge_pull_request` or `gh pr merge --delete-branch`) — that
+  flag is silently skipped when a PR auto-closes without a normal merge
+  commit (e.g., duplicate rebase scenarios).
+- **Always** treat a "remote ref not found" error from the delete command as a
+  non-fatal, idempotent success — the branch is already gone.
+- **Always** use `--force-with-lease` (never bare `--force`) when pushing
+  rebased branches to avoid overwriting concurrent pushes.
+- **Always** explicitly close the GitHub PR via
+  `mcp__github__update_pull_request` with `state: "closed"` in Step 6 after
+  branch cleanup. Because this workflow pushes directly to the base branch,
+  GitHub will **never** auto-close the PR — it must be closed manually
+  every time.
+- **Always** post a Step 7 summary comment for auditability, even if no fixes
+  were required.

package/.agents/workflows/git-pr-all.md

@@ -0,0 +1,278 @@
+---
+description: >-
+  Stage all outstanding changes, commit, push to a feature branch, and open a
+  pull request with native auto-merge enabled.
+---
+
+# /git-pr-all [Message] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
+
+This workflow is the **ad-hoc PR ergonomics** counterpart to the heavyweight
+`/epic-deliver` pipeline. Use it when you have outstanding changes that do not
+belong to a planned Epic (typo fixes, file deletions, doc tweaks, dependency
+bumps, operator housekeeping) and you want a single command to take them from
+the working tree to a PR queued for auto-merge.
+
+It composes the three steps that used to live in
+[`/git-commit-all`](git-commit-all.md), [`/git-push`](git-push.md), and a
+manual `gh pr create` — no more dance, no more manually slugging branch
+names. Quality gates remain enforced by the existing pre-push hook; this
+workflow does not bypass them.
+
+> **When to run**: After making changes on `main` (or any base branch) that
+> are too small or too out-of-band for `/epic-plan` + `/epic-deliver` but
+> still need to land via the PR-required flow.
+>
+> **Persona**: `devops-engineer` · **Skills**:
+> `core/git-workflow-and-versioning`
+
+---
+
+## Arguments
+
+```text
+/git-pr-all [Message] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
+```
+
+- `Message` — the commit subject. First line becomes the PR title; if
+  the message contains a blank line, everything after the blank line
+  becomes the PR body. When omitted, an interactive prompt is suppressed
+  and a timestamped fallback (`chore: ad-hoc changes <ISO>`) is used.
+- `--draft` — open the PR in draft state and skip the auto-merge enable
+  step. Useful when you want CI to run before flipping to ready-for-review.
+- `--no-auto-merge` — open a normal (non-draft) PR but do not enable
+  GitHub's native auto-merge queue. The operator merges through the UI
+  when ready. Default behaviour is `gh pr merge --auto --squash --delete-branch`.
+- `--branch <name>` — override the auto-generated feature branch name.
+  When omitted, the branch is slugged from the commit subject (see
+  Step 2).
+- `--base <branch>` — override the merge target. When omitted, reads
+  `project.baseBranch` from `.agentrc.json` (default `main`).
+
+---
+
+## Step 0 — Resolve Context
+
+1. Resolve `[BASE_BRANCH]` from `--base` or `.agentrc.json` →
+   `project.baseBranch` (default `main`).
+2. Read the current branch with `git rev-parse --abbrev-ref HEAD`.
+3. Determine the operating mode:
+   - **`from-base` mode** — current branch equals `[BASE_BRANCH]`. The
+     workflow must cut a feature branch in Step 2 before committing.
+   - **`from-feature` mode** — current branch is anything else. The
+     workflow commits + pushes to the existing branch in Step 3 and
+     opens (or updates) a PR from it.
+4. Verify the working tree has outstanding changes with
+   `git status --porcelain`. If the output is empty: **STOP** and tell
+   the operator there is nothing to PR.
+
+---
+
+## Step 1 — Compose Commit Message
+
+If the operator passed `[Message]`, use it verbatim. Otherwise, fall back
+to `chore: ad-hoc changes <ISO 8601 timestamp>` so the commit is never
+unmessageable.
+
+Split the message on the first blank line:
+
+- **Subject** — the first line, used as the commit subject AND the PR
+  title.
+- **Body** — everything after the first blank line, used as the commit
+  body AND the PR body. May be empty.
+
+---
+
+## Step 2 — Cut Feature Branch (from-base mode only)
+
+Skip this step in `from-feature` mode — the branch already exists.
+
+When `--branch <name>` is set, use it verbatim. Otherwise generate a
+branch slug from the commit subject:
+
+1. Detect the Conventional Commit type prefix (`<type>(<scope>): …`).
+   If matched, use `<type>` as the branch namespace. Allowed types:
+   `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `build`, `ci`,
+   `perf`, `style`. Anything else (or no prefix) → `chore`.
+2. Strip the type prefix and any leading punctuation from the subject.
+3. Lowercase, replace non-alphanumeric runs with `-`, collapse repeated
+   hyphens, trim leading/trailing hyphens.
+4. Truncate to 50 chars on a word boundary.
+5. Combine: `<type>/<slug>`. Example: `"Delete unused files"` →
+   `chore/delete-unused-files`. `"fix(observability): drop stale handler"`
+   → `fix/observability-drop-stale-handler`.
+
+Cut and check out the branch:
+
+```powershell
+git checkout -b <branch-name>
+```
+
+If a local branch with that name already exists: pick a fresh name by
+appending `-2` (then `-3`, etc.) until `git rev-parse --verify` returns
+non-zero, and check that out instead.
+
+---
+
+## Step 3 — Stage + Commit
+
+Stage all outstanding changes:
+
+```powershell
+git add -A
+```
+
+> **Why `-A` and not explicit paths?** `/git-pr-all` is operator-driven
+> (not parallel-agent-driven), so the single-tree assumption that
+> blocks `git add .` inside `/story-deliver` does not apply here. See
+> the parallel-execution warning at the bottom of this file.
+
+Commit:
+
+```powershell
+git commit -m "<subject>" -m "<body>"
+```
+
+If the body is empty, omit the second `-m`. If the pre-commit hook
+fails:
+
+1. Read the failure output.
+2. Fix the issue (run `npm run format`, fix lint errors, etc.).
+3. `git add -A` again.
+4. Re-run `git commit` (do **not** pass `--no-verify`).
+
+---
+
+## Step 4 — Push with Upstream
+
+Push the branch and set its upstream so subsequent pushes do not need
+the explicit ref:
+
+```powershell
+git push -u origin <branch-name>
+```
+
+If the pre-push hook fails:
+
+1. Read the failure output.
+2. Fix the offending baseline / test / lint issue in the working tree.
+3. `git add -A`, `git commit --amend --no-edit` (the original commit
+   has not been pushed yet, so amend is safe).
+4. Re-run the push.
+
+If the pre-push hook is correctly blocking a real regression, fix the
+regression — never bypass the hook with `--no-verify`.
+
+---
+
+## Step 5 — Open PR
+
+```powershell
+gh pr create --base <BASE_BRANCH> --head <branch-name> \
+  --title "<subject>" --body "<body-or-default>"
+```
+
+When `--body` would otherwise be empty, fall back to a single line:
+`Opened via /git-pr-all`. Pass `--draft` to `gh pr create` when the
+operator set the `--draft` flag.
+
+Capture the resulting PR URL from `gh pr create`'s stdout for the
+final summary.
+
+---
+
+## Step 6 — Enable Auto-Merge (default)
+
+Skip this step when `--draft` or `--no-auto-merge` is set.
+
+```powershell
+gh pr merge <PR_NUMBER> --auto --squash --delete-branch
+```
+
+This queues the PR for merge as soon as required checks turn green and
+schedules deletion of the head branch on merge. Auto-merge requires
+`allow_auto_merge: true` on the repo (set by `/agents-bootstrap-github`,
+Story #1239).
+
+If `gh pr merge --auto` fails (missing repo feature, insufficient
+token scope), log the failure and surface it to the operator — the PR
+itself remains open and mergeable through the GitHub UI.
+
+---
+
+## Step 7 — Summary
+
+Print a single block to the operator:
+
+```text
+✅ Opened PR #<PR_NUMBER>: <subject>
+   <PR_URL>
+   branch: <branch-name> → <BASE_BRANCH>
+   auto-merge: <enabled | draft | disabled>
+```
+
+Do **not** poll CI. That is the `/epic-deliver` Phase 7 job and is
+overkill for ad-hoc changes. The operator (or GitHub's email
+notification) is the next watcher.
+
+---
+
+## Troubleshooting
+
+- **Hook failures**: Treat the same way `/git-push` does — read the
+  output, fix the underlying issue, never `--no-verify`. The pre-push
+  hook (lint + format + maintainability + audit + coverage + CRAP) is
+  the same gate every PR has to pass eventually; failing here lets you
+  fix it before opening the PR rather than after CI fails.
+- **Branch already exists locally**: appended `-2`/`-3` per Step 2; this
+  is the same behaviour `gh repo` uses. If you want a specific name,
+  pass `--branch <name>` explicitly.
+- **`gh pr create` fails with "no commits between branches"**: the push
+  in Step 4 did not actually move the branch (e.g., it was already at
+  the same SHA as `[BASE_BRANCH]`). Verify `git log <BASE_BRANCH>..HEAD`
+  shows commits before re-running.
+- **PR template wins over `--body`**: if `.github/pull_request_template.md`
+  exists, `gh pr create --body` overrides it. To opt into the template
+  flow, drop the `--body` flag in Step 5 and pass `--editor` instead —
+  but that requires an interactive session. For ad-hoc PRs the explicit
+  body is the right default.
+- **Auto-merge does not fire after CI green**: confirm the PR's required
+  checks match the auto-merge requirements. The framework's quality gate
+  (`Validate and Test`) is the canonical required check; other checks
+  may be informational. Use the GitHub UI's "Merge when ready" surface
+  to inspect the queue state.
+
+---
+
+## Constraint
+
+- **Never** push directly to `[BASE_BRANCH]`. Step 2's branch cut is
+  mandatory in `from-base` mode; remove it and the workflow becomes a
+  silent bypass of the PR-required policy.
+- **Never** pass `--no-verify` to `git commit` or `git push` to bypass
+  the quality gate. Fix the failure at the source.
+- **Never** force-push from `/git-pr-all`. This workflow is for opening
+  new PRs, not for rewriting history. Force-pushes belong to
+  `/git-merge-pr` (with `--force-with-lease` after a rebase) and
+  `/epic-deliver` Phase 7 (with the operator's explicit context).
+- **Always** delete the head branch on merge (Step 6's
+  `--delete-branch` flag handles this for `--auto` mode; for
+  `--no-auto-merge` PRs the operator is responsible for the cleanup).
+- **Always** prefer `--auto --squash --delete-branch` unless the
+  operator explicitly opts out. The squash + auto-merge default gives
+  the same merge ergonomics `/epic-deliver` produces, so main's commit
+  history stays uniform across both surfaces.
+
+---
+
+## ⚠️ Parallel Story Execution
+
+Do **not** use this workflow from inside a parallel story-execution
+context (`/story-deliver #<storyId>`, `/epic-deliver` wave dispatch).
+`git add -A` sweeps any untracked files in the working tree, which in
+a shared working directory may belong to another agent. Use the
+explicit-staging + branch-guard pattern documented in
+`story-deliver.md` Step 1 in those contexts.
+
+The same warning applies to any workflow that calls `git add .` or
+`git add -A`; this is not unique to `/git-pr-all` (see
+[`git-push.md`](git-push.md) for the canonical version).