mandrel 1.91.0 → 1.92.0

package/.agents/workflows/git-deliver.md

@@ -9,18 +9,15 @@ description: >-
 
 # /git-deliver [Message] [--no-push] [--pr] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
 
-This workflow is the **single source of truth** for getting outstanding
-working-tree changes out the door when they do not belong to a planned Epic
-(typo fixes, file deletions, doc tweaks, dependency bumps, operator
-housekeeping). It is the ad-hoc counterpart to the heavyweight `/deliver`
-pipeline.
-
-It replaces the retired `/git-commit-all`, `/git-push`, and `/git-pr-all`
-commands: instead of choosing a command by how far you want to go, you run
-one command and it **detects the git setup** and escalates to the correct
-terminal step. Flags pin any level explicitly; the interactive choice prompt
-fires **only** when the detected state is genuinely ambiguous, so the common
-path stays non-interactive and scriptable.
+The **single source of truth** for getting outstanding working-tree changes
+out the door when they do not belong to a planned Epic (typo fixes, doc
+tweaks, dependency bumps, operator housekeeping, benchmark result commits
+from mandrel-bench's `/benchmark` Step 4). It is the ad-hoc counterpart to
+the heavyweight `/deliver` pipeline: one command that **detects the git
+setup** and escalates to the correct terminal step. Flags pin any level
+explicitly; the interactive choice prompt fires **only** when the detected
+state is genuinely ambiguous, so the common path stays non-interactive and
+scriptable.
 
 > **Persona**: `devops-engineer` · **Skills**:
 > `core/git-workflow-and-versioning`
@@ -47,35 +44,30 @@ it is about to run** before it acts.
 /git-deliver [Message] [--no-push] [--pr] [--draft] [--no-auto-merge] [--branch <name>] [--base <branch>]
 ```
 
-- `Message` — the commit subject. First line becomes the commit subject (and,
-  at the **pr** level, the PR title); if the message contains a blank line,
-  everything after it becomes the commit/PR body. When omitted, a timestamped
-  fallback (`chore: ad-hoc changes <ISO 8601>`) is used so the commit is never
+- `Message` — commit subject (and, at the **pr** level, the PR title); text
+  after the first blank line becomes the commit/PR body. When omitted, fall
+  back to `chore: ad-hoc changes <ISO 8601>` so the commit is never
   unmessageable.
-- `--no-push` — force the **commit** level: stage and commit only, no push.
-  Useful when chaining several commits or deferring the push.
-- `--pr` — force the **pr** level even from a feature branch where a plain
-  push would otherwise be the default.
+- `--no-push` — force the **commit** level.
+- `--pr` — force the **pr** level even from a feature branch.
 - `--draft` — (pr level) open the PR in draft state and skip arming
-  auto-merge. Useful when you want CI to run before flipping to
-  ready-for-review.
-- `--no-auto-merge` — (pr level) open a normal (non-draft) PR but do not enable
-  GitHub's native auto-merge queue. The operator merges through the UI.
-  Default at the pr level is `gh pr merge --auto --squash --delete-branch`.
+  auto-merge.
+- `--no-auto-merge` — (pr level) open a normal PR but do not enable native
+  auto-merge; the operator merges through the UI.
 - `--branch <name>` — (pr level) override the auto-generated feature branch
-  name. When omitted, the branch is slugged from the commit subject (Step 3).
-- `--base <branch>` — override the base branch used for detection and as the PR
-  merge target. When omitted, reads `project.baseBranch` from `.agentrc.json`
-  (default `main`).
+  name.
+- `--base <branch>` — override the base branch used for detection and as the
+  PR merge target. Default: `project.baseBranch` from `.agentrc.json`
+  (fallback `main`).
 
 ---
 
 ## Boot sweep
 
-Before detecting the git setup, run the **protected boot sweep** so
-`/git-deliver` starts from a tidy local checkout — a feature branch this
-command opened and pushed on a prior run, once its PR has merged, is reaped
-here rather than left to accumulate:
+Before detecting the git setup, run the **protected boot sweep** so the run
+starts from a tidy local checkout — a feature branch this command opened on a
+prior run, once its PR has merged, is reaped here rather than left to
+accumulate:
 
 ```bash
 node .agents/scripts/boot-sweep.js \
@@ -84,240 +76,81 @@ node .agents/scripts/boot-sweep.js \
   --current "$(git rev-parse --abbrev-ref HEAD)"
 ```
 
-This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
-base branch (`main`), prunes stale remote-tracking refs, and reaps every local
-branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
-It **never** touches the stash stack, and its `evaluateProtection` partition
-skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
-still-open parent ticket; `--current` always excludes the branch you are on.
-The sweep is **silent on a no-op** — nothing merged, `main` already current →
-one summary line (`[boot-sweep] reaped 0 local + 0 remote; protected 0.`). Its
-exit code is always `0`; a failed sweep is reported in that summary, never
-allowed to fail the delivery run.
+The safe subset of the `/git-cleanup` phases: fast-forwards the base branch,
+prunes stale remote-tracking refs, and reaps merged branches. It never
+touches the stash, never reaps a candidate with unpushed work / dirty
+worktree / open parent ticket, and always exits `0` — a failed sweep is
+reported in its summary line, never allowed to fail the delivery run.
 
 ---
 
 ## Step 0 — Detect Git Setup & Resolve Level
 
-1. Resolve `[BASE_BRANCH]` from `--base` or `.agentrc.json` →
-   `project.baseBranch` (default `main`).
-2. Read the current branch: `git rev-parse --abbrev-ref HEAD`.
-3. 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 deliver.
-4. Detect whether a remote is configured: `git remote`.
-5. Resolve the **terminal level** from flags + state:
+1. Resolve `[BASE_BRANCH]` (`--base` → `.agentrc.json` → `main`).
+2. Read the current branch; verify `git status --porcelain` shows outstanding
+   changes — if empty, **STOP**: nothing to deliver.
+3. Resolve the **terminal level** from flags + state:
    - `--no-push` set → **commit**.
    - No remote configured → **commit** (warn there is nowhere to push).
    - `--pr` set → **pr**.
    - Current branch equals `[BASE_BRANCH]` → **pr** (a direct push to the
-     protected base would be rejected, so the PR flow is the only safe path).
-   - Otherwise (a feature branch with a remote) → **push**.
-6. **Ambiguity gate.** Surface an interactive choice **only** when the state is
-   genuinely under-determined — for example a **detached HEAD**, or a feature
-   branch with a remote but no upstream tracking ref where pushing would need
-   `-u`. Present the operator the candidate levels (e.g. "push to a new
-   upstream" vs. "open a PR") and proceed with their pick. In every
-   non-ambiguous case, do **not** prompt — announce the detected level and
-   continue.
-7. Echo a one-line plan to the operator before acting, e.g.
+     protected base would be rejected).
+   - Otherwise (feature branch with a remote) → **push**.
+4. **Ambiguity gate.** Prompt the operator **only** when state is genuinely
+   under-determined — e.g. a detached HEAD, or a feature branch with a remote
+   but no upstream tracking ref (push `-u` vs. open a PR). In every
+   non-ambiguous case, do **not** prompt.
+5. Echo a one-line plan before acting, e.g.
    `detected: on feature branch 'fix/foo' with upstream → level: push`.
 
 ---
 
-## Step 1 — Compose Commit Message
-
-If the operator passed `[Message]`, use it verbatim. Otherwise fall back to
-`chore: ad-hoc changes <ISO 8601 timestamp>`.
-
-Split the message on the first blank line:
-
-- **Subject** — the first line; commit subject and (pr level) PR title.
-- **Body** — everything after the first blank line; commit body and (pr level)
-  PR body. May be empty.
-
----
-
-## Step 2 — Stage + Commit (all levels)
-
-Stage all outstanding changes:
-
-```powershell
-git add -A
-```
-
-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`.
-
-**If the level is `commit`, stop here** and print the commit summary.
-
----
-
-## Step 3 — Cut Feature Branch (pr level, from-base only)
-
-Only when the level is **pr** *and* the current branch equals `[BASE_BRANCH]`.
-Skip when already on a feature branch.
-
-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`.
-
-Cut and check out the branch **before committing** — that is, when this step
-applies, run it ahead of Step 2's commit so the commit lands on the feature
-branch, never on the base branch:
-
-```powershell
-git checkout -b <branch-name>
-```
-
-If a local branch with that name already exists, append `-2` (then `-3`, …)
-until `git rev-parse --verify` returns non-zero, and check that out instead.
-
----
-
-## Step 4 — Push (push and pr levels)
-
-Push the current branch. At the **push** level, push to the existing upstream:
-
-```powershell
-git push
-```
+## Steps 1–6 — Deliver at the resolved level
 
-At the **pr** level (or any branch lacking an upstream), set the upstream:
+Commit, push, and PR mechanics are host-native git/`gh` competency; run them
+directly, honoring these contracts:
 
-```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`, then create a **new follow-up commit** (do not amend a commit
-   that has already been pushed; amending an unpushed commit is fine).
-4. Re-run the push. Never bypass the hook with `--no-verify`.
-
-If the push is rejected because the remote has work you do not have locally,
-`git pull --rebase`, resolve conflicts, and push again.
-
-**If the level is `push`, stop here** and print the push summary.
-
----
-
-## Step 5 — Open PR (pr level)
-
-```powershell
-gh pr create --base <BASE_BRANCH> --head <branch-name> \
-  --title "<subject>" --body "<body-or-default>"
-```
-
-When the body would otherwise be empty, fall back to a single line:
-`Opened via /git-deliver`. Pass `--draft` to `gh pr create` when the operator
-set `--draft`. Capture the PR URL from stdout for the summary.
-
----
-
-## Step 6 — Arm Auto-Merge (pr level, default)
-
-Skip when `--draft` or `--no-auto-merge` is set.
-
-```powershell
-gh pr merge <PR_NUMBER> --auto --squash --delete-branch
-```
-
-This queues the PR to merge as soon as required checks turn green and schedules
-head-branch deletion on merge. Auto-merge requires `allow_auto_merge: true` on
-the repo. If `gh pr merge --auto` fails (missing repo feature, insufficient
-token scope), log the failure and surface it — the PR stays open and mergeable
-through the GitHub UI.
-
----
-
-## Step 7 — Summary
-
-Print a single block matched to the level that ran:
-
-```text
-# commit level
-✅ Committed on <branch>: <subject>
-
-# push level
-✅ Committed + pushed <branch> → origin: <subject>
-
-# pr level
-✅ Opened PR #<PR_NUMBER>: <subject>
-   <PR_URL>
-   branch: <branch-name> → <BASE_BRANCH>
-   auto-merge: <enabled | draft | disabled>
-```
-
-Do **not** poll CI. That is the `/deliver` Phase 7 job and is overkill for
-ad-hoc changes. The operator (or GitHub's email notification) is the next
-watcher.
-
-> **Local ref left behind — reaped at the next boot.** At the **pr** level
-> this command leaves a local feature branch behind after the PR merges; it
-> does **not** reap it inline (the merge happens later, out of band). You do
-> not need to run `/git-cleanup` by hand: the next time `/git-deliver` (or
-> `/plan`) runs, its **Boot sweep** step reaps that merged ad-hoc branch and
-> fast-forwards `main` automatically. The delivering flow owns tidying its own
-> refs on the next boot — see
-> [`.agents/rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md).
-
----
+- **Branch cut (pr level, from-base only).** Cut the feature branch **before
+  committing** so the commit never lands on the base branch. Branch name:
+  `--branch` verbatim, else `<type>/<slug>` — Conventional Commit type from
+  the subject (unrecognized/absent → `chore`), subject slugged to lowercase
+  hyphenated ≤50 chars. Name collision → append `-2`/`-3`/….
+- **Stage + commit.** `git add -A`, then commit with the composed
+  subject/body.
+- **Push.** `git push` (existing upstream) or `git push -u origin <branch>`.
+  Rejected because the remote is ahead → `git pull --rebase`, resolve, push
+  again.
+- **Hook failures (commit or push).** Read the output, fix the underlying
+  issue, re-stage, and (for an already-pushed commit) add a **new follow-up
+  commit** rather than amending. **Never** `--no-verify`.
+- **PR + auto-merge (pr level).** `gh pr create --base [BASE_BRANCH]`
+  with the subject/body (empty body → `Opened via /git-deliver`; pass
+  `--draft` through). Then, unless `--draft`/`--no-auto-merge`:
+  `gh pr merge --auto --squash --delete-branch`. If arming fails (repo
+  feature missing, token scope), log and surface it — the PR stays open and
+  mergeable through the UI.
 
-## Troubleshooting
+Stop at the resolved level and print a one-block summary naming the branch,
+subject, and (pr level) PR URL + auto-merge state.
 
-- **Hook failures**: 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 3; pass
-  `--branch <name>` for a specific name.
-- **`gh pr create` fails with "no commits between branches"**: the push did not
-  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. 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.
+Do **not** poll CI — that is the `/deliver` Phase 7 job and is overkill for
+ad-hoc changes. The local feature branch left behind at the pr level is
+reaped by the next run's Boot sweep — see
+[`.agents/rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md).
 
 ---
 
 ## Constraint
 
-- **Never** push directly to `[BASE_BRANCH]`. At the pr level Step 3'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** push directly to `[BASE_BRANCH]`. The from-base branch cut is
+  mandatory; remove it and the workflow becomes a silent bypass of the
+  PR-required policy.
+- **Never** pass `--no-verify` to `git commit` or `git push`. Fix the failure
+  at the source.
 - **Never** force-push from `/git-deliver`. This workflow opens new PRs, it
-  does not rewrite history. Force-pushes belong to `/git-merge-pr` (with
-  `--force-with-lease` after a rebase) and `/deliver` Phase 7.
+  does not rewrite history.
 - **Always** prefer `--auto --squash --delete-branch` at the pr level unless
-  the operator opts out, so `main`'s commit history stays uniform across the
+  the operator opts out, so `main`'s history stays uniform across the
   `/git-deliver` and `/deliver` surfaces.
 
 ---

package/.agents/workflows/helpers/_merge-conflict-template.md

@@ -1,7 +1,7 @@
 # Merge Conflict Resolution — Shared Procedure
 
 Canonical, workflow-agnostic procedure for resolving merge / rebase conflicts.
-Referenced by `git-merge-pr.md`, `deliver-stories.md`, and `deliver-epic.md`.
+Referenced by `deliver-stories.md` and `deliver-epic.md`.
 
 ## Procedure
 

package/.agents/workflows/helpers/code-review.md

@@ -427,8 +427,8 @@ in-place.
 1. **Apply a focused fix on `[HEAD_REF]`.** Permitted only when the
    finding is unambiguously *fixable* (clean remediation, no scope
    creep, no spec deviation, no secret exposure):
-   - Call [`assert-branch.js`](../../scripts/assert-branch.js) with
-     `--expected [HEAD_REF]` before touching the working tree.
+   - Confirm `git branch --show-current` reports `[HEAD_REF]` before
+     touching the working tree; if it does not, STOP and re-checkout.
    - Stage explicit paths only (never `git add .`).
    - Make one focused conventional commit per finding
      (`fix(<scope>): <description> (review finding)`).
@@ -461,9 +461,9 @@ ceremony above:
 1. Group the fixable Mediums by owning lens (the pillar or audit family
    that produced them). A Medium is fixable on the same terms as a 🟠; a
    Medium in any escalation class stays on the comment exactly like a 🟠.
-2. For each lens, call `assert-branch.js --expected [HEAD_REF]`, stage
-   explicit paths only, and make **one focused conventional commit per
-   lens** (`fix(<scope>): <description> (review findings batch)`).
+2. For each lens, confirm `git branch --show-current` reports
+   `[HEAD_REF]`, stage explicit paths only, and make **one focused
+   conventional commit per lens** (`fix(<scope>): <description> (review findings batch)`).
 3. Bounded-attempt semantics extend to the batch: each finding gets **at
    most one** attempt, and a lens's batch commit that would exceed
    `delivery.codeReview.maxFixScopeFiles` routes that lens's findings to
@@ -549,7 +549,8 @@ If the operator instructs you to fix any findings:
 
    ```powershell
    # Guard: confirm we're on the correct branch before committing.
-   node .agents/scripts/assert-branch.js --expected [HEAD_REF]
+   # ([HEAD_REF] mismatch -> STOP and re-checkout before any commit.)
+   git branch --show-current
 
    # Stage explicit paths — never `git add .` on a shared tree.
    git add <path/one> <path/two>

package/.agents/workflows/helpers/deliver-epic.md

@@ -769,14 +769,15 @@ run. Passing `--epic <epicId>` scopes the red-path failure digest to
   `gh run view --log-failed` tail, coarse classification) and surfaces
   the fix-loop handoff. Remediate on `epic/<epicId>` and re-run the
   helper (auto-merge stays armed across retries). If the same failure
-  class recurs, hand the convergence off to the host loop:
-  `/loop /loops:fix-failing-tests`.
+  class recurs, hand the convergence off to a self-paced host loop
+  (`/loop`) that re-runs the failing check and applies the smallest fix
+  until it exits green.
 - **Exit 2** — **still-running** (slow CI, not red): the poll cap fired
   with checks still pending and the watcher exhausted its
   `delivery.ci.watch.maxResumes` re-arm budget with nothing red. This is
   **never** a failure and **never** `timed_out`. Hand the wait off to the
-  host's interval loop rather than blocking the delivery turn:
-  `/loop 5m /loops:watch-ci`.
+  host's interval loop rather than blocking the delivery turn: `/loop 5m`
+  polling `gh pr checks` until the checks settle.
 
 > **Triage authority.** How to classify and remediate a red (or repeatedly
 > slow) check — the root-cause-only decision tree for infra/transient and