mandrel 1.70.0 → 1.71.0

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

@@ -0,0 +1,298 @@
+---
+description: >-
+  Single ad-hoc delivery command for working-tree changes. Detects the git
+  setup and escalates to the right terminal step — commit only, commit + push,
+  or commit + push + open a PR with native auto-merge — picking the default
+  from observable state and letting flags pin any level explicitly. Replaces
+  the retired git-commit-all, git-push, and git-pr-all trio.
+---
+
+# /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.
+
+> **Persona**: `devops-engineer` · **Skills**:
+> `core/git-workflow-and-versioning`
+
+---
+
+## Terminal levels
+
+| Level | Terminal action | Default trigger |
+| ----- | --------------- | --------------- |
+| **commit** | stage + commit on the current branch | `--no-push`, **or** no git remote is configured |
+| **push** | + push the current branch to its upstream | on a feature branch (current ≠ base branch) with a remote |
+| **pr** | + cut/push a feature branch, open a PR, arm auto-merge | on the base branch (a direct push would bounce off branch protection), **or** `--pr` is set |
+
+The detection only sets the **default**. Every level is reachable by an
+explicit flag, and the command **announces what it detected and which level
+it is about to run** before it acts.
+
+---
+
+## Arguments
+
+```text
+/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
+  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.
+- `--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`.
+- `--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`).
+
+---
+
+## 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:
+   - `--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.
+   `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
+```
+
+At the **pr** level (or any branch lacking an upstream), set the upstream:
+
+```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.
+
+---
+
+## Troubleshooting
+
+- **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.
+
+---
+
+## 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** 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.
+- **Always** prefer `--auto --squash --delete-branch` at the pr level unless
+  the operator opts out, so `main`'s commit history stays uniform across the
+  `/git-deliver` and `/deliver` surfaces.
+
+---
+
+## ⚠️ Parallel Story Execution
+
+Do **not** use this workflow from inside a parallel story-execution context
+(`/deliver #<storyId>`, `/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. In those contexts stage explicit paths only and
+confirm `git branch --show-current` reports the expected `story-<id>` branch
+before committing — see
+[`helpers/worktree-lifecycle.md`](helpers/worktree-lifecycle.md) for the
+shared-tree hazard and the worktree-isolation model that contains it.

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

@@ -6,12 +6,12 @@ description: QA Epic-testing workflow — ingest the agent-driven QA harness swe
 
 > **Helper module.** Not a slash command. Invoked from the QA gate during
 > `/deliver` or directly by an operator when the Epic-testing ticket
-> needs refreshed evidence. For ad-hoc acceptance runs use `/qa-run-harness` —
+> needs refreshed evidence. For ad-hoc acceptance runs use `/qa-run` —
 > this helper owns the Epic-evidence ticket lifecycle on top of it.
 
 Gather and attach the acceptance-suite evidence that gates Epic closure. The
 evidence artifact is the **agent-driven QA harness sweep report** produced by
-`/qa-run-harness` (scenario pass/fail/blocked totals plus structured
+`/qa-run` (scenario pass/fail/blocked totals plus structured
 findings), **not** a hand-ticked markdown checklist.
 
 > **When to run**: During the QA phase of an Epic, after all Story merges
@@ -38,13 +38,13 @@ findings), **not** a hand-ticked markdown checklist.
 
 ## Step 1 — Execute the QA Harness Sweep
 
-Invoke `/qa-run-harness` with the chosen selector:
+Invoke `/qa-run` with the chosen selector:
 
 ```text
-/qa-run-harness "tag:@smoke and @risk-high"
+/qa-run "tag:@smoke and @risk-high"
 ```
 
-The `/qa-run-harness` workflow (`.agents/workflows/qa-run-harness.md`) owns the
+The `/qa-run` workflow (`.agents/workflows/qa-run.md`) owns the
 execution mechanics — `qa` contract resolution, scenario selection, browser
 navigation, and finding capture. This workflow consumes its output.
 
@@ -117,7 +117,7 @@ and deleting the checklist in the same change.
 
 ## Cross-References
 
-- Execution mechanics: `.agents/workflows/qa-run-harness.md`.
+- Execution mechanics: `.agents/workflows/qa-run.md`.
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
 - Runner / fixture / trace conventions:
   `.agents/skills/stack/qa/playwright-bdd/SKILL.md`.

package/.agents/workflows/helpers/{agents-sync-config.md → mandrel-sync-config.md}

@@ -5,15 +5,16 @@ description: >-
   surfacing redundant keys (project values that already match framework
   defaults). The runtime layers defaults at read time, so the helper never
   auto-fills optional keys from the template. Invoked by reference from
-  /agents-update.
+  /mandrel-update.
 ---
 
-# agents-sync-config (helper)
+# mandrel-sync-config (helper)
 
 > **Not a slash command.** Lives under `.agents/workflows/helpers/` so it is
 > not projected into the mandrel plugin command tree. Invoked by reference from
-> [`/agents-update`](../agents-update.md) after a framework update; previously
-> shipped as `/agents-sync-config`. The reconciliation runs as part of the
+> [`/mandrel-update`](../mandrel-update.md) after a framework update; previously
+> shipped as the standalone `/agents-sync-config` command (later demoted to a
+> helper, then renamed alongside `/mandrel-update`). The reconciliation runs as part of the
 > `mandrel update` upgrade path (bump → sync → migrate → doctor).
 >
 > **Configuration reference.** The full set of configurable keys, defaults,

package/.agents/workflows/{agents-update.md → mandrel-update.md}

@@ -10,7 +10,7 @@ description: >-
   stage + commit the staged lockfile bump.
 ---
 
-# /agents-update
+# /mandrel-update
 
 > **Upgrade owner.** The mechanical upgrade is owned end to end by the
 > [`mandrel update`](../../lib/cli/update.js) CLI under the npm distribution
@@ -23,7 +23,7 @@ description: >-
 
 ## Overview
 
-`/agents-update` advances the consumer repo to the newest published
+`/mandrel-update` advances the consumer repo to the newest published
 `mandrel` release, re-materializes `.agents/`, and regenerates the
 flat `.claude/commands/` tree (invoked as `/<name>`) against the new workflow
 set — then reconciles the consumer's own config, harness allowlist, and
@@ -105,7 +105,7 @@ day-0 failure modes — **wrong project**, a **dirty git index**, and being
 consumer repo root:
 
 ```bash
-node .agents/scripts/agents-update-preflight.js
+node .agents/scripts/mandrel-update-preflight.js
 ```
 
 The preflight runs three checks and prints a JSON envelope
@@ -243,8 +243,8 @@ CLI's stderr names it) and run the matching manual remedy from the consumer
 repo root. These commands match the hint strings
 [`lib/cli/update.js`](../../lib/cli/update.js) emits verbatim — it is the
 single source of truth, kept in lockstep with this table by the
-`agents-update-recovery-drift` contract test
-([`tests/bootstrap/agents-update-recovery-drift.test.js`](../../tests/bootstrap/agents-update-recovery-drift.test.js)):
+`mandrel-update-recovery-drift` contract test
+([`tests/bootstrap/mandrel-update-recovery-drift.test.js`](../../tests/bootstrap/mandrel-update-recovery-drift.test.js)):
 
 | Failed phase      | Manual remedy                                            |
 | ----------------- | ------------------------------------------------------- |
@@ -319,7 +319,7 @@ The helper (Story #1995) is **default-aware** and **read-only**:
   modified.
 
 Full procedure reference:
-[`helpers/agents-sync-config.md`](helpers/agents-sync-config.md).
+[`helpers/mandrel-sync-config.md`](helpers/mandrel-sync-config.md).
 
 If the helper prints `No changes required` with no advisories, the config
 is already in sync — carry on. If it lists `[REDUNDANT]` rows, you may
@@ -392,7 +392,7 @@ rest of the per-Epic temp tree):
   contract for the framework.
 
 A second run produces `no-change` on every install path, which is the
-guarantee `agents-update`'s idempotence contract requires.
+guarantee `mandrel-update`'s idempotence contract requires.
 
 ## Step 3.6 — Refresh the harness permission allowlist (`/fewer-permission-prompts`)
 
@@ -431,7 +431,7 @@ auto-applied change:
 - Apply the accepted subset by editing `.claude/settings.json` and
   stage it alongside the version bump in Step 5.
 
-The maintenance cadence is **once per `/agents-update` invocation** —
+The maintenance cadence is **once per `/mandrel-update` invocation** —
 the same operator who just ran `mandrel update` is the one with the
 freshest transcript context to review the proposed allowlist
 diff. Skipping the step is fine when the bump introduces no new

package/.agents/workflows/qa-explore.md

@@ -19,7 +19,7 @@ operator watches and gates.** Its human-led sibling is
 the agent scribes/enriches. No human-driven flow lives in `/qa-explore`; if you
 want to capture something *you* observed, use `/qa-assist` instead.
 
-Unlike [`/qa-run-harness`](qa-run-harness.md) (which steps a known set of
+Unlike [`/qa-run`](qa-run.md) (which steps a known set of
 Gherkin `.feature` scenarios through a browser), `/qa-explore` is **open-ended
 exploration**: the agent probes the surface for product bugs, environment-setup
 friction, tooling/DX gaps, missing tests, and enhancement ideas — each captured

package/.agents/workflows/{qa-run-harness.md → qa-run.md}

@@ -2,7 +2,7 @@
 description: Drive Gherkin scenarios through a real browser as an agent-driven QA sweep
 ---
 
-# /qa-run-harness
+# /qa-run
 
 Execute a consumer's Gherkin `.feature` scenarios through a **real browser**
 (the chrome-devtools MCP surface), with the agent acting as the step executor
@@ -31,7 +31,7 @@ console filtering.
 ## Slash Command
 
 ```text
-/qa-run-harness <selector>
+/qa-run <selector>
 ```
 
 ### Arguments
@@ -58,9 +58,9 @@ deterministic, `(file, line)`-sorted scenario set under the contract's
 ### Examples
 
 ```text
-/qa-run-harness feature:login
-/qa-run-harness "tag:@smoke and not @wip"
-/qa-run-harness domain:billing
+/qa-run feature:login
+/qa-run "tag:@smoke and not @wip"
+/qa-run domain:billing
 ```
 
 The canonical tag taxonomy — `@smoke`, `@risk-high`, `@platform-web`,

package/README.md

@@ -158,6 +158,26 @@ npx mandrel sync                        # re-materialize ./.agents/
 npx mandrel doctor                      # verify the install
 ```
 
+## Benchmarking
+
+Mandrel's effectiveness is measured by a separate companion repo,
+**[mandrel-bench](https://github.com/dsj1984/mandrel-bench)** — a *consumer* of
+the published `mandrel` package. It pins a specific framework version,
+materializes it via `mandrel sync`, and drives Mandrel's own `/plan`→`/deliver`
+pipeline (plus a bare-model control) over a scenario corpus. Each run is scored
+across five dimensions — Quality, Planning fidelity, and Autonomy (what the
+scaffolding *buys*) versus Efficiency and Overhead ratio (what it *costs*) —
+reported as distributions with a noise-band, tracking the framework's
+**value-add over the bare-model baseline** across versions and models.
+
+The benchmark lives in its own repo on purpose: holding the harness fixed while
+varying the pinned `mandrel` version cleanly decouples harness-version from
+framework-version, and running through the published-package + `mandrel sync`
+path exercises the real consumer contract. The dependency is one-directional —
+`mandrel-bench` depends on `mandrel`, never the reverse. See the
+[mandrel-bench README](https://github.com/dsj1984/mandrel-bench#readme) for the
+dimensions, run model, and how to benchmark a new version.
+
 ## Contributors
 
 Only `.agents/` is distributed to consumers — it ships inside the

package/docs/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.70.0...mandrel-v1.71.0) (2026-06-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **workflows:** three operator-facing slash commands are renamed and three git commands are consolidated. Consumers must update muscle memory and any scripts: `/agents-update`→`/mandrel-update`, `/qa-run-harness`→`/qa-run`, and `/git-commit-all` / `/git-push` / `/git-pr-all`→`/git-deliver` (detection picks the old behavior by default; `--no-push` reproduces `/git-commit-all`, a feature-branch run reproduces `/git-push`, and a base-branch run or `--pr` reproduces `/git-pr-all`).
+
+### Changed
+
+* **workflows:** rename agents-update→mandrel-update, qa-run-harness→qa-run; collapse 3 git commands into git-deliver ([#4209](https://github.com/dsj1984/mandrel/issues/4209)) ([fc30a3d](https://github.com/dsj1984/mandrel/commit/fc30a3d579d80fd854217e066f97899b813c6be9))
+
 ## [1.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.69.0...mandrel-v1.70.0) (2026-06-16)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.70.0",
+  "version": "1.71.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",

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

@@ -1,15 +0,0 @@
----
-description: Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push).
----
-
-# /git-commit-all [Message]
-
-This is a compatibility alias for [`/git-push --no-push`](git-push.md) — it
-stages and commits all outstanding changes without pushing. See
-[`git-push.md`](git-push.md) for the canonical procedure, hook-failure guidance,
-and the parallel-execution warning.
-
-## Constraint
-
-Follow every constraint in [`git-push.md`](git-push.md) — this alias does not
-relax any of them.