mandrel 1.70.0 → 1.72.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/helpers/plan-epic.md

@@ -74,14 +74,22 @@ Phase 5 (Re-Plan Detection).
    one-pager feeds the scope-triage gate below, whose verdict folds into
    the **same** Phase 1 HITL confirmation. Do not stop twice.
 
-3. **HITL stop — confirm the sharpened one-pager**: Display the one-pager
-   to the operator and **STOP**. Do not proceed to Phase 2 until the
-   user explicitly confirms the direction. This is the same gate the
-   skill's own Phase 3 enforces; surfacing it here makes the wait
+3. **HITL stop — confirm the sharpened one-pager** (**gate #1**): Display
+   the one-pager to the operator and **STOP**. Do not proceed to Phase 2
+   until the user explicitly confirms the direction. This is the same gate
+   the skill's own Phase 3 enforces; surfacing it here makes the wait
    contract visible to `/plan` callers. When the Phase 1.5 verdict is
    `story` or `borderline`, this stop carries the three-way choice the
    triage gate defines (below) instead of a plain confirm.
 
+   > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
+   > `--yes`, this gate does **not** STOP: the one-pager confirm resolves as
+   > **approved** and the run continues to Phase 2. A `story` / `borderline`
+   > triage verdict resolves to its **Recommended** branch (below) rather
+   > than prompting the three-way choice. Display the one-pager and the
+   > verdict line for the record, then proceed without waiting. See
+   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
 ## Phase 1.5: Scope Triage (ideation path only)
 
 This phase runs **only** on the ideation path, immediately after Phase 1
@@ -124,6 +132,15 @@ skill states once).
    avoid the ceremony tax of pushing a story-sized scope through the full Epic
    pipeline.
 
+   > **`--yes` (headless) exception.** "Never auto-route" is the interactive
+   > contract. Under `--yes` the operator has *pre-authorized* the
+   > recommendation: the three-way choice resolves to its **Recommended**
+   > branch deterministically — `single Story` hands off to
+   > `/plan --from-notes <path>` (carrying `--yes` so the receiving story
+   > path also auto-proceeds), and an `epic` verdict simply continues to
+   > Phase 2. No operator wait. This is the only sanctioned auto-route, and it
+   > exists solely to make `/plan` driveable headlessly.
+
 ## Phase 2: Cross-Epic Duplicate Search
 
 Runs immediately after Phase 1 (and only on the s-plan-ideation path).
@@ -396,6 +413,19 @@ for the scoring logic.
    permission") is honored — no `gh issue edit` call until the
    operator confirms.
 
+   > **`--yes` (headless) auto-proceed.** This refinement-diff confirm is the
+   > clarity-gate face of `/plan`'s **gate #1** on the existing-Epic
+   > (`/plan <epicId>`) path — it is an operator *wait*, not a deterministic
+   > validator (the deterministic half is the section-presence *scoring* in
+   > step 1, which always runs). When `/plan` was invoked with `--yes`, this
+   > confirm does **not** STOP: the sharpened body is auto-**approved** and the
+   > run proceeds to step 6 (persist). The blast-radius note is still displayed
+   > for the record; only the operator wait is suppressed. This keeps
+   > `/plan <epicId> --yes` driveable headlessly even when the Epic body needs
+   > refinement (`gh issue edit` still runs only via the step 6 persist call,
+   > which the auto-approval authorizes). See
+   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
 6. **Persist**: On approval, run the persist mode:
 
    ```bash
@@ -556,18 +586,31 @@ for the scoring logic.
      `planningRisk.requiresReview` unless the operator passed
      `--force-review`:
      - **High risk** (`requiresReview === true`) or **operator override**
-       (`--force-review`): **STOP**. Ask the USER to review the generated
-       PRD, Tech Spec, and Acceptance Spec on GitHub. Approval is the
-       user's verbal OK in this session — the three context tickets stay
+       (`--force-review`) — **gate #2**: **STOP**. Ask the USER to review the
+       generated PRD, Tech Spec, and Acceptance Spec on GitHub. Approval is
+       the user's verbal OK in this session — the three context tickets stay
        **open** through delivery and are closed automatically by
        `/deliver` when the Epic PR opens. Do NOT proceed
        to decomposition until the user confirms the plan is accurate.
+
+       > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
+       > `--yes`, this review gate does **not** STOP, even when
+       > `requiresReview === true` or `--force-review` was also passed: the
+       > review resolves as **approved** and the run **continues directly to
+       > Phase 8**, exactly as the low-risk auto-proceed branch below. The
+       > three context tickets stay **open** through delivery as usual; only
+       > the operator *wait* is suppressed. This is `/plan`'s **gate #2** —
+       > the second and last HITL STOP `--yes` suppresses. `--yes` does
+       > **not** alter risk routing or the review criteria themselves; it
+       > only forces a proceed where this gate would otherwise STOP. See
+       > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
      - **Low risk** (`requiresReview === false` and no `--force-review`):
        Emit the auto-proceed message from the persist stdout
        (`reviewRouting.operatorMessage`) and **continue directly to Phase 8**
        without an extra review stop. The Epic still carries
        `agent::review-spec` until decomposition completes; the routing
-       decision is recorded in the `epic-plan-state` checkpoint.
+       decision is recorded in the `epic-plan-state` checkpoint. (`--yes` is
+       a no-op on this branch — there is no STOP to suppress.)
 
 5. **Tech Spec freshness check (advisory)**: After the Tech Spec issue
    is created, `epic-plan-spec.js` runs

package/.agents/workflows/helpers/plan-story.md

@@ -68,6 +68,9 @@ to authoring the standalone Story body from the handed-off one-pager.
 
 # Inspect the draft body without creating an Issue:
 /plan --dry-run --body temp/single-story-draft.md
+
+# Headless / non-interactive (auto-proceeds the draft-confirm gate):
+/plan --idea "rip out the unused TaskBodyMigrator export" --yes
 ```
 
 ## Phase 1 — Emit Context
@@ -153,8 +156,18 @@ add a second stop.
 
 Display the draft to the operator and **STOP**. Do not call the persist phase
 until the operator explicitly confirms the draft. This mirrors the HITL gate
-`/plan` Phase 3 enforces before opening the Epic Issue. The scope-triage
-verdict folds into this same stop:
+`/plan` Phase 3 enforces before opening the Epic Issue. This is the
+story-path face of `/plan`'s **gate #1** (the ideation one-pager /
+scope-triage confirm). The scope-triage verdict folds into this same stop:
+
+> **`--yes` (headless) auto-proceed.** When `/plan` was invoked with `--yes`,
+> this gate does **not** STOP: the draft confirm resolves as **approved** and
+> the run proceeds to Phase 3 (persist). An `epic` verdict resolves to its
+> **Recommended** branch — escalate to `/plan --idea` (carrying `--yes`),
+> abandoning the draft — rather than prompting the three-way choice. Display
+> the draft and the verdict line for the record, then proceed without
+> waiting. See
+> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
 
 - **`story` verdict (or gate skipped via handoff)** → no extra prompt. The
   operator confirms the draft as usual and the run proceeds to Phase 3
@@ -177,6 +190,9 @@ verdict folds into this same stop:
 
   **Never auto-route.** The verdict is advisory; the operator always decides,
   and no `agent::*` / label transition happens on either side of the choice.
+  (**`--yes` exception:** headless mode pre-authorizes the **Recommended**
+  branch deterministically — see the `--yes` note above — the only sanctioned
+  auto-route, present solely to make `/plan` driveable without an operator.)
 
 ## Phase 3 — Persist (`gh issue create`)
 

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/plan.md

@@ -44,6 +44,7 @@ forwards them to the active path helper:
 | `--force` | Epic | Close + recreate an existing ticket tree on re-plan. |
 | `--force-review` | Epic | Force the operator review gate even when risk routing would skip it. |
 | `--allow-over-budget` | Epic | Permit a decomposition that exceeds the framework `maxTickets` reviewability budget. |
+| `--yes` | both | **Non-interactive / headless mode.** Deterministically auto-proceeds the two `/plan` HITL STOP gates — the ideation one-pager / scope-triage confirm (gate #1) and the Phase-7 Epic operator review gate (gate #2) — without waiting for operator input. Parallel to [`/deliver --yes`](deliver.md). Composes with `--allow-over-budget` and with the risk-routed Phase-7 skip (it forces a proceed where those do not apply). Default (flag absent) behavior is unchanged: both gates still STOP for interactive use. |
 | `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
 | `--dry-run` | both | Author + validate without GitHub writes. |
 | `--body <path>` | Story | Pre-authored Story body file; validate (and create, unless `--dry-run`) without re-authoring. |
@@ -58,6 +59,71 @@ commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is now
 an **internal branch switch** inside this router: same skills, same
 helpers, no command hop and no operator re-entry.
 
+### Headless / non-interactive mode (`--yes`)
+
+`--yes` is the headless escape hatch for an unattended driver (CI, a
+benchmark harness, or any `claude -p` run with no human at the keyboard). It
+is the `/plan`-side parallel of [`/deliver --yes`](deliver.md), which
+suppresses that command's segment-plan confirmation. `/plan` has exactly
+**two** HITL STOP gates, and `--yes` deterministically auto-proceeds **both**
+without waiting for operator input:
+
+1. **Gate #1 — the ideation one-pager / scope-triage / clarity confirm.**
+   This single conceptual gate has three faces depending on the entry form,
+   and `--yes` auto-proceeds **all three**:
+   - On the `--idea` Epic path,
+     [`helpers/plan-epic.md`](helpers/plan-epic.md) Phase 1 (folding in the
+     Phase 1.5 scope-triage verdict) STOPs to confirm the sharpened one-pager.
+   - On the `--idea` Story path,
+     [`helpers/plan-story.md`](helpers/plan-story.md) Phase 2 STOPs to
+     confirm the drafted Story body.
+   - On the existing-Epic (`/plan <epicId>`) path, the Phase 6 Epic Clarity
+     Gate's **needs-refinement** branch STOPs to confirm the refined-body
+     diff before persisting it.
+
+   Under `--yes` each auto-proceeds: the one-pager / draft / refined-body
+   confirm resolves as **approved**, and a `story` / `borderline` triage
+   verdict resolves to its **recommended** branch (the one the gate prose
+   marks "Recommended") rather than prompting the three-way choice. The
+   verdict / clarity scoring is still recorded in chat (one line); only the
+   *wait* is suppressed. The clarity-gate *scoring* itself (deterministic
+   section-presence in Phase 6 step 1) still runs — `--yes` suppresses only
+   the operator confirm of the proposed refinement.
+2. **Gate #2 — the Phase-7 Epic operator review gate.** When risk routing
+   forces a review (`planningRisk.requiresReview === true`, or the operator
+   also passed `--force-review`),
+   [`helpers/plan-epic.md`](helpers/plan-epic.md) Phase 7 STOPs for operator
+   approval of the PRD / Tech Spec / Acceptance Spec before decomposition.
+   Under `--yes` this review auto-proceeds straight to Phase 8 — the three
+   context tickets stay **open** through delivery exactly as on the low-risk
+   auto-proceed path.
+
+**Composition.** `--yes` is orthogonal to the other planning flags and
+composes cleanly:
+
+- With **`--allow-over-budget`**: `--yes` suppresses the gate *waits* while
+  `--allow-over-budget` still governs the `maxTickets` over-budget persist —
+  passing `--yes` alone does **not** waive the budget gate.
+- With the **risk-routed Phase-7 skip**: when risk routing already skips the
+  Phase-7 review (low-risk, no `--force-review`), `--yes` is a no-op for that
+  gate — it only *forces a proceed where the gate would otherwise STOP*, it
+  never *adds* a stop or relaxes any non-HITL validator.
+
+**`--yes` suppresses only the HITL operator *waits* above.** It does **not**
+relax any deterministic gate — the Phase 6 Epic Clarity Gate **scoring**
+(section-presence), the Phase 7.5 Tech Spec Section Gate, the file-assumption
+/ DAG validators, the Phase 10 readiness healthcheck, and the `agent::blocked`
+runtime pause all behave exactly as without the flag. A `--yes` run that hits
+one of those still fails closed; the flag is an operator-input suppressor, not
+a validation override. The other operator-input *waits* in the pipeline also
+auto-proceed under `--yes` — the non-blocking Phase 2 duplicate-search pause
+(distinct-Epic confirmed), the Phase 6 clarity refinement-diff confirm
+(refined body approved), and the advisory Phase 8.3/8.4/8.5
+consolidation/critic diffs (consolidated/critic output applied) — since they
+are operator-input waits, not validators. The two *named* HITL STOP gates the
+Story tracks (gate #1, gate #2) are the load-bearing pair; these additional
+waits are auto-proceeded for the same headless reason.
+
 ## First-run preflight
 
 Before routing to a path helper, run a **first-run preflight** to catch
@@ -109,9 +175,11 @@ stubbed docs, or an unready doctor verdict).
    [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
    seed. Record the verdict in chat (one line).
 4. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry phase, forwarding the absorbed flags. The helper's phase
-   numbering, HITL gates, and scripts are unchanged — this router adds no
-   phase content.
+   from its entry phase, forwarding the absorbed flags (including `--yes`).
+   The helper's phase numbering, HITL gates, and scripts are unchanged — this
+   router adds no phase content. When `--yes` is present, the two HITL STOP
+   gates auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
+   above; every deterministic gate still runs.
 5. **Internal returns.** When a path helper would historically have handed
    off to the other planning command, switch helpers in-place and continue;
    surface the switch to the operator as a one-line note.

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