mandrel 1.69.0 → 1.71.0

package/.agents/scripts/mandrel-update-preflight.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+
+/**
+ * mandrel-update-preflight.js — Story #4170
+ * (feat(mandrel-update): add a first-run preflight before the updater)
+ *
+ * A first-run preflight for the `/mandrel-update` workflow. The workflow
+ * otherwise jumps straight to `npx mandrel update` with no guard rails;
+ * this preflight catches three day-0 failure modes *before* the version
+ * bump:
+ *
+ *   1. **Wrong project (hard stop).** Running the updater in the framework
+ *      repo itself or in a non-consumer (no `mandrel` dependency in
+ *      `package.json`, or no materialized `.agents/` directory) silently
+ *      does the wrong thing. The consumer-shape check is a BLOCKER: it
+ *      exits non-zero so the workflow halts before bumping anything.
+ *   2. **Dirty git index (warn).** `mandrel update` deliberately leaves the
+ *      lockfile *staged* (see `lib/cli/update.js`); the workflow's commit
+ *      step then `git add`s and commits. If the index already holds
+ *      unrelated staged changes, that step would sweep them into the
+ *      `chore: update mandrel` commit. Warn so the operator can unstage
+ *      first.
+ *   3. **Offline (warn).** The CLI throws a usable error on a failed
+ *      `npm view`, but a one-line up-front reachability check gives a
+ *      friendlier "you're offline" signal before any version probe.
+ *
+ * Severity is consistent with framework preflight conventions
+ * (cf. `story-close.js` runStoryClosePreflight, `epic-deliver-preflight.js`):
+ * the consumer-shape check is a hard stop (blocker), dirty-index and offline
+ * are warn-only and never block the run.
+ *
+ * Out of scope (per the Story): folding these checks into
+ * `lib/cli/update.js` itself — the CLI stays git-free and
+ * side-effect-scoped; this is a workflow-layer concern.
+ *
+ * The detection logic is a pure function (`runMandrelUpdatePreflight`) that
+ * takes injectable probes so it is unit-testable without touching the real
+ * filesystem, git index, or network. The CLI wrapper wires the real probes
+ * and maps a blocker finding to a non-zero exit code.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * @typedef {object} PreflightFinding
+ * @property {string} id        Stable check id.
+ * @property {'blocker'|'warning'} severity
+ * @property {string} summary   One-line human-readable description.
+ * @property {string} [fix]     Copy-pasteable remediation hint.
+ */
+
+/**
+ * Real-world probes. Each is overridable in tests via the `probes` option.
+ *
+ * @param {string} projectRoot Absolute consumer repo root.
+ */
+export function makeProbes(projectRoot) {
+  return {
+    /**
+     * Read + parse `package.json`. Returns the parsed object, or `null`
+     * when the file is missing or unparseable.
+     */
+    readPackageJson() {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      if (!existsSync(pkgPath)) return null;
+      try {
+        return JSON.parse(readFileSync(pkgPath, 'utf8'));
+      } catch {
+        return null;
+      }
+    },
+    /** Does the materialized `.agents/` directory exist? */
+    agentsDirExists() {
+      return existsSync(path.join(projectRoot, '.agents'));
+    },
+    /**
+     * Are there staged (index) changes? Returns true when
+     * `git diff --cached --name-only` is non-empty. Returns false on any
+     * git error (not a repo, git missing) — a missing index is not a
+     * dirty index.
+     */
+    hasStagedChanges() {
+      try {
+        const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim().length > 0;
+      } catch {
+        return false;
+      }
+    },
+    /**
+     * Is the npm registry reachable? Probes `npm ping` (a PM-agnostic
+     * reachability query that does not mutate anything). Returns true when
+     * the ping succeeds, false on any failure (offline / registry down).
+     */
+    registryReachable() {
+      try {
+        execFileSync('npm', ['ping'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'ignore', 'ignore'],
+          timeout: 10_000,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Pure preflight evaluator. Runs the three checks against the supplied
+ * probes and returns a structured result. Never throws; never performs
+ * I/O directly (all I/O is behind `probes`).
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof makeProbes>} options.probes
+ * @returns {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }}
+ *   `blocked` is true when any blocker-severity finding fired (the
+ *   consumer-shape hard stop). `ok` is true when there are no findings of
+ *   any severity.
+ */
+export function runMandrelUpdatePreflight({ probes }) {
+  /** @type {PreflightFinding[]} */
+  const findings = [];
+
+  // 1. Consumer-shape check — BLOCKER (hard stop).
+  const pkg = probes.readPackageJson();
+  const deps = pkg
+    ? {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.optionalDependencies ?? {}),
+      }
+    : {};
+  const hasMandrelDep = Object.hasOwn(deps, 'mandrel');
+  const hasAgentsDir = probes.agentsDirExists();
+
+  if (!pkg || !hasMandrelDep || !hasAgentsDir) {
+    const missing = [];
+    if (!pkg) missing.push('no readable package.json');
+    else if (!hasMandrelDep)
+      missing.push('package.json does not list "mandrel" as a dependency');
+    if (!hasAgentsDir) missing.push('no .agents/ directory');
+    findings.push({
+      id: 'consumer-shape',
+      severity: 'blocker',
+      summary: `Not a Mandrel consumer project (${missing.join('; ')}). Run /mandrel-update from a consumer repo that depends on "mandrel" and has a materialized .agents/ tree — not the framework repo itself or an unrelated project.`,
+      fix: 'cd into the consumer project root, or run `npm install -D mandrel && npx mandrel sync` to bootstrap one.',
+    });
+  }
+
+  // 2. Dirty-index check — WARN only.
+  if (probes.hasStagedChanges()) {
+    findings.push({
+      id: 'dirty-index',
+      severity: 'warning',
+      summary:
+        "The git index already has staged changes. `mandrel update` leaves the lockfile staged, and the workflow's commit step (Step 5) would sweep these unrelated staged files into the `chore: update mandrel` commit.",
+      fix: 'Unstage unrelated changes first: `git restore --staged <path>` (or `git reset` to clear the whole index), then re-run the preflight.',
+    });
+  }
+
+  // 3. Offline check — WARN only.
+  if (!probes.registryReachable()) {
+    findings.push({
+      id: 'offline',
+      severity: 'warning',
+      summary:
+        'The npm registry is not reachable. `npx mandrel update` resolves the newest published version via the registry and will fail its version probe while offline.',
+      fix: 'Check your network connection (or registry auth/proxy config) before running `npx mandrel update`.',
+    });
+  }
+
+  const blocked = findings.some((f) => f.severity === 'blocker');
+  return { ok: findings.length === 0, blocked, findings };
+}
+
+/**
+ * Render the findings to a logger. Blockers go to `error`, warnings to
+ * `warn`. A clean result logs a single `info` line.
+ *
+ * @param {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }} result
+ * @param {{ info: Function, warn: Function, error: Function }} logger
+ */
+export function reportPreflight(result, logger) {
+  if (result.ok) {
+    logger.info(
+      '✅ [mandrel-update-preflight] All checks passed — safe to run `npx mandrel update`.',
+    );
+    return;
+  }
+  for (const f of result.findings) {
+    const line = `[${f.id}] ${f.summary}${f.fix ? `\n  ↳ Fix: ${f.fix}` : ''}`;
+    if (f.severity === 'blocker') {
+      logger.error(`❌ ${line}`);
+    } else {
+      logger.warn(`⚠️  ${line}`);
+    }
+  }
+  if (result.blocked) {
+    logger.error(
+      '[mandrel-update-preflight] Hard stop: do not run `npx mandrel update` until the blocker above is resolved (exit 2).',
+    );
+  } else {
+    logger.warn(
+      '[mandrel-update-preflight] Warnings only — review them, then proceed if intentional.',
+    );
+  }
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const probes = makeProbes(projectRoot);
+  const result = runMandrelUpdatePreflight({ probes });
+  reportPreflight(result, Logger);
+  // Machine-parsable JSON envelope on stdout for tooling / the workflow to
+  // read. Use process.stdout.write (not console.log) per the no-console
+  // enforcement boundary: human-facing output goes through Logger above.
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return result.blocked ? 2 : 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'mandrel-update-preflight',
+  propagateExitCode: true,
+});

package/.agents/scripts/providers/github/issues.js

@@ -99,6 +99,54 @@ export class IssuesGateway {
     return issues.filter((issue) => !issue?.pull_request);
   }
 
+  /**
+   * Search issues by a free-text query via the REST search API
+   * (`GET /search/issues`). Deliberately REST, **not** GraphQL: transient
+   * GraphQL 401s are a known failure mode in this repo (the dedup port that
+   * consumes this method must not silently no-op on an auth blip), so the
+   * search rides the same `gh api` REST surface + transient-retry shim as
+   * every other read here.
+   *
+   * The caller (`audit-to-stories.js` `loadProvider()`) passes a 40-char
+   * fingerprint sha as the query so the search resolves the handful of
+   * issues whose fingerprint footer carries that sha; `route-finding.js`
+   * then confirms identity against the footer. Both open and closed issues
+   * are returned (no `state:` qualifier is appended) so a closed-fingerprint
+   * match can surface as `regression-of-closed`.
+   *
+   * Returns the trimmed `[{ number, state, body }]` projection the dedup
+   * port expects. `state` is normalised to the REST lowercase form
+   * (`open` / `closed`).
+   *
+   * @param {{ query: string, owner?: string, repo?: string }} params
+   * @returns {Promise<Array<{ number: number, state: string, body: string }>>}
+   * @field-manifest GET /search/issues: total_count, items[number, state, body]
+   */
+  async searchIssues({ query, owner, repo } = {}) {
+    if (typeof query !== 'string' || query.trim().length === 0) {
+      throw new Error('searchIssues: a non-empty query string is required');
+    }
+    const scopeOwner = owner ?? this.owner;
+    const scopeRepo = repo ?? this.repo;
+    // Constrain the search to this repo and to issues (not PRs). The
+    // fingerprint sha is the free-text term; GitHub matches it against the
+    // issue body where the `<!-- audit-fingerprints: ... -->` footer lives.
+    const qualifiers = [`repo:${scopeOwner}/${scopeRepo}`, 'type:issue'];
+    const q = `${query.trim()} ${qualifiers.join(' ')}`;
+    const endpoint = `/search/issues?q=${encodeURIComponent(q)}`;
+    const result = await withTransientRetry(
+      () => this._gh.api({ method: 'GET', endpoint }),
+      { label: `searchIssues ${query}`, onRetry: defaultRetryWarn },
+    );
+    const json = parseApiJson(result);
+    const items = Array.isArray(json?.items) ? json.items : [];
+    return items.map((item) => ({
+      number: item.number,
+      state: item.state ?? 'open',
+      body: item.body ?? '',
+    }));
+  }
+
   /**
    * List Epic-typed issues. Filter shape preserved from the old code.
    *

package/.agents/scripts/providers/github.js

@@ -98,6 +98,7 @@ export class GitHubProvider extends ITicketingProvider {
  */
 const DELEGATIONS = [
   ['graphql', 'issues.ghGraphql'],
+  ['searchIssues', 'issues.searchIssues'],
   ['listIssuesByLabel', 'issues.listIssuesByLabel'],
   ['getEpics', 'issues.getEpics'],
   ['getEpic', 'issues.getEpic'],

package/.agents/scripts/sync-agentrc.js

@@ -4,8 +4,8 @@
  * sync-agentrc.js — default-aware `.agentrc.json` reconciliation (Story #1995).
  *
  * Replaces the manual procedure formerly described in
- * `.agents/workflows/helpers/agents-sync-config.md`. Invoked by
- * `/agents-update` Step 3 after the package upgrade re-materializes `.agents/`.
+ * `.agents/workflows/helpers/mandrel-sync-config.md`. Invoked by
+ * `/mandrel-update` Step 3 after the package upgrade re-materializes `.agents/`.
  *
  * Contract:
  *   - Validates the project config against the framework schema. On

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-16T00:37:23.856Z",
+  "generatedAt": "2026-06-16T16:35:27.286Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -577,7 +577,7 @@
       "tier": "stack",
       "category": "qa",
       "path": ".agents/skills/stack/qa/qa-harness/SKILL.md",
-      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run-harness` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run-harness.md`; this skill is the conventions reference it leans on.",
+      "description": "Conventions for the agent-driven QA harness that drives Gherkin scenarios through a real browser. Use when executing `/qa-run` or instrumenting a live surface — covers navigation-first execution, per-surface console and network capture, design-token visual checks, and the framework-generic heuristic cards for turning signal into findings. The harness procedure lives in `.agents/workflows/qa-run.md`; this skill is the conventions reference it leans on.",
       "policyCapsuleBullets": 8,
       "allowedTools": null,
       "vendor": null

package/.agents/skills/stack/qa/playwright-bdd/SKILL.md

@@ -71,7 +71,7 @@ authoring.
   single `defineBddConfig` block that lists `features` and `steps` paths.
 - Register the Cucumber HTML/JSON reporter alongside the Playwright HTML
   reporter so a headless CI invocation emits machine-readable evidence
-  alongside the agent-driven `/qa-run-harness` sweep.
+  alongside the agent-driven `/qa-run` sweep.
 - Use Playwright projects (not Cucumber profiles) for browser matrix fan-out —
   keeps sharding, retries, and trace config in one place.
 
@@ -99,7 +99,7 @@ authoring.
   tag vocabularies in the runner config; extend via `@domain-*` only.
 - Wire tag-filtered headless runs to a single npm script so operators never
   reconstruct the generate-then-run sequence by hand; the agent-driven
-  `/qa-run-harness` selector mirrors the same tag expressions for browser sweeps.
+  `/qa-run` selector mirrors the same tag expressions for browser sweeps.
 - Fail the run if generation produces zero matching scenarios — a silent empty
   suite is worse than a red build.
 
@@ -184,5 +184,5 @@ those outcomes.
 
 - Scenario authoring rules: `.agents/rules/gherkin-standards.md`.
 - Browser-level conventions: `.agents/skills/stack/qa/playwright/SKILL.md`.
-- Operator entry point: `.agents/workflows/qa-run-harness.md`.
+- Operator entry point: `.agents/workflows/qa-run.md`.
 - Evidence handoff: `.agents/workflows/helpers/epic-testing.md`.

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -2,11 +2,11 @@
 name: qa-harness
 description:
   Conventions for the agent-driven QA harness that drives Gherkin scenarios
-  through a real browser. Use when executing `/qa-run-harness` or instrumenting
+  through a real browser. Use when executing `/qa-run` or instrumenting
   a live surface — covers navigation-first execution, per-surface console and
   network capture, design-token visual checks, and the framework-generic
   heuristic cards for turning signal into findings. The harness procedure lives
-  in `.agents/workflows/qa-run-harness.md`; this skill is the conventions
+  in `.agents/workflows/qa-run.md`; this skill is the conventions
   reference it leans on.
 ---
 
@@ -26,7 +26,7 @@ description:
 Guidance for executing the agent-driven QA harness through a real browser (the
 chrome-devtools MCP surface). The harness **procedure** — argument parsing,
 step ordering, contract resolution sequence — is the SSOT in
-[`.agents/workflows/qa-run-harness.md`](../../../../workflows/qa-run-harness.md);
+[`.agents/workflows/qa-run.md`](../../../../workflows/qa-run.md);
 this skill shows **how** to apply the instrumentation and inspection
 conventions that procedure depends on. The assertion-tier rules it enforces
 live in [`testing-standards.md`](../../../../rules/testing-standards.md)
@@ -212,7 +212,7 @@ QA evidence ticket.
 
 ## 7. Cross-References
 
-- Run procedure (SSOT): [`qa-run-harness.md`](../../../../workflows/qa-run-harness.md).
+- Run procedure (SSOT): [`qa-run.md`](../../../../workflows/qa-run.md).
 - Console filter module: [`console-allowlist.js`](../../../../scripts/lib/qa/console-allowlist.js).
 - Assertion-tier rules: [`testing-standards.md`](../../../../rules/testing-standards.md).
 - Scenario prose: [`gherkin-authoring`](../gherkin-authoring/SKILL.md).

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.